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How To Use This Manual 


Look over the general table of contents and the tables of contents of the two 
major sections and the five appendices. 


Read Subsections 1.0 and 2.0. These give a general overview of the operating 
system and the language. Look through Appendix A. Subsection A.1 is a set 
of reference tables to the system and the language. The syntax of the utility 
invocations and all of the expressions and statements of the language are listed 
here, followed by a set of tables of control functions and keyword groups, 
including record sizing and control options. Material which is not understood 
ean be cross-referenced in the glossary in Appendix E and in Sections 1 or 2, 
via the index also contained in Appendix E. The second half of Appendix A 
contains three sample programs. They contain routines for screen display, file 
I/O and printer output, illustrating some of the usage of the language. 


Experienced programmers will now begin practice on the F-85. Writing modular 
subroutines to perform specific functions is recommended, both for practice on 
a small seale before a large project is attempted and to begin building a set 
of useful utility subroutines and functions for later use. Less experienced 
programmers will want to read the relevant subsection of the manual completely 
before beginning practice writing, while more experienced programmers will want 
to refer to the main sections only when a problem appears. In either case, a 
full reading of the manual would be useful but is probably not required before 
practice begins. 


The discussion of disk file structure in Appendix B should be examined closely 
when practice of disk I/O is begun. Understanding the I/O statements’ use is 
much simpler when the file's disk organization is understood. Likewise, users 
with the multi-tasking options should read the discussion of multi-user pro- 
gramming in Appendix C before beginning practice in multi-tasking. Also in 
Appendix C is a discussion of the similarities and differences between D-BASIC 
and STAR BASIC, followed by a discussion of CONVERT and FILECON, the 
conversion utilities. Appendix:D holds the error message tables, while Appendix 
E has the glossary and index. 


This is not intended to be a text book on programming but rather a reference 
book. The reference tables in Appendix A will help you practice writing in 
STAR BASIC, supplemented by the relevant sections of the text, consulted when 
necessary. The language is powerful and flexible; the system contains a wide 
variety of useful tools. They await your use. 
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SECTION 1 
THE DX-85M OPERATING SYSTEM AND ITS UTILITIES 
1.0  DX-85M OVERVIEW 


The DX-85M operating system and its utilities provide full, flexible, efficient control 
of the F-85 computer system with a number of important features: 


Multi-tasking: with the appropriate optional hardware, DX-85M supports up to 
five separate STAR BASIC programs running independently. 


Program development: the EDIT, COMPILE, RUN and RUNB utilities provide 
an effective program development and debugging system. The STAR BASIC 
language is a flexible, efficient, business-oriented high level programming 
language which, with the tools available from the system, makes applications 
development and debugging faster and easier. NOTE: As the text refers to 
RUN, it is referring to RUN or RUNB, whichever the user has selected. 


System configuration; DX-85M gives the user control over the I/O configuration 
ot the operating system. The number of open files, the number of sequential 


and ISAM buffers, the existence of the ISAM file manager in the system, the 
number and type of disk units, and the configuration of the multi-communications 
ports (if any) are all controlled by a user-created control file. 


Turnkey operation: another control file allows creation of turnkey systems which 
automatically load and run upon system startup, in either single user or multiple 
user modes. 


The system consists of a main loading file, several control files (two of them optional, 
user-created files), the ISAM file system, a set of system utilities and a set of RUN 
utilities. 


Users should consult the F-85 Operator's Manual (Durango part number 100326-001) for 
instruction on the operation of the F-85. Familiarity with that manual (including how 
to turn on the machine, load diskettes, load the system, load paper, and so on) is 
assumed here. 


The initial section of the DX-85M operating system consists of the following disk files: 


DX85Mnumber the operating system loading file 
STARTU.SYS the startup control file 

ISAM.SYS the ISAM file system 

[ CONFIG.SYS ] the optional configuration control file 
[$AUTOSTART ] the optional turnkey control file 


After power up and CODE LOAD, the system searches for and loads the type "L" file, 
DX85Mnumber. STARTU.SYS is used for startup parameters. 


If a CONFIG.SYS control file is found in the diskette directory, that file is used to 
configure the system I/O. It sets the maximum number of open files, whether the 
ISAM file manager is active, how many sequential and ISAM buffers are used, the 
number and type of disk units active, and, if the multi-communications options are 
available, to configure the multi-communications ports. If no CONFIG.SYS file is 
found (it is user-created, through the CONFIGURE or EDIT utilities), default values 
are used. 
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If a $AUTOSTART file is present, the system goes through an input routine to set the 
date and time in the system clock, then uses the contents of the $AUTOSTART file 
as if it were keyboard input. Normally $AUTOSTART calls the runtime monitor and 
an object code program file to be run, for finished, turnkey applications. 


If no $AUTOSTART file is present (it is user-created, using the EDIT utility), the 
system does not ask for the date and time for the clock but immediately goes to the 
system command level, giving the colon prompt (:). 


The system command level responds to several system commands (see Subsection 1.17) 
used primarily for system debugging. Any input other than the system commands is 
assumed to be a machine code program file: the system will attempt to find, load 
and run a program from the file name specified. The standard programs run from the 
system command level are the system utilities: 


EDIT editor, writes or rewrites source code files 
COMPILE compiler, compiles object code from source code 
RUNX load optional system support modules and begin RUN or RUNB 
RUN runtime monitor, runs object code programs 
RUNB same function as RUN, requires expanded memory 
BATCH batch mode control program 

COPY file copy utility 

FILES file directory utility 

BDUMP disk data blocks display utility 

FORMAT disk formatting utility 

DSCAN disk error scanning utility 


COMPILE may also use a library file which holds one or more standard STAR BASIC 
routines for inclusion in other programs. Any properly "book-marked" file may be used 
as the COMPILE library file. A standard library file, BASIC.LIB, is supplied with the 
system, however, containing a set of transcendental functions and a number of other 
useful routines. 


The control files CONFIG.SYS and $AUTOSTART, and the system utilities are discussed 
in separate subsections numbered 1.1 through 1.12. 


In addition to the system utilities and control files, several utilities have been written 
in STAR BASIC. These run under RUN just like any other STAR BASIC program and 
ean be chained to from a running application, if desired, just like other STAR BASIC 
object code file. 


The RUN, or RUNB utilities are invoked by inputting the utility name to the RUN 
command prompt, the asterisk *. Each of the RUN utilities is self-prompting. 
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Syntax Definitions 


The invoeation of each of the system utilities and the commands which they respond 
to are given in syntax definitions similar, but not always identical to, the syntax 
definitions given in the language section of this manual. Invocations are defined like 
this: 


definition: utility name invocation 


: utility name control or parameters 


where utility name is the name of the utility being invoked, : is the system command 
prompt and controls or parameters are the other needed parts of the invocation. 


The following syntactic conventions apply: square brackets mark optional elements; 
underlined words are syntactic variables and are replaced by the appropriate (indicated) 
expressions or elements in functioning invocations or commands; all other characters 
are literals which must appear as shown in functioning invocations or commands. 


The system utilities are invoked from the : system command prompt. The RUN utilities 
are invoked from the * RUN command prompt. Once within a utility, there may be 
a command prompt (as the * prompt in RUN); this will be explained in the utility's 
subsection. 


In general, the form name/unit number is used to indicate file name on unit unit 
number. Disk unit designators always default to unit 0, so this is the form used in 
syntax definitions (using the EDIT invocation as an example): 


definition: EDIT invocation 
: EDIT[/unit number][* filenamei[/unit number] [filename2[/unit number] ] 


The : is the system command prompt; EDIT is the utility file name; /unit number 
(abbreviated to /unit in most other definitions) is a / followed by an integer, the 
integer specifying the disk unit, defaulting to disk unit 0 if omitted; the * is an 
optional literal: if used, it causes the EDIT to be done in the large video font; if 
omitted, the small video font is used; filenamel would be replaced by the name of a 
source file; filename2 would be replaced by the name of the output file; if omitted 
a backup name system is used (see Subsection 1.2 for details). 


The expressions within brackets[ are optional; their default values are given in the 
text below the sysntax definition. 
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1.1 CONFIG.SYS 


Creation of a CONFIG.SYS control file allows the user to tailor the file structure of 
the DX-85M operating system to fit the application, allowing substantial speed or 
memory gains. CONFIG.SYS also (optionally) controls the I/O characteristics of the 
multi-port serial interface (F-85 Option 8530). 


When the system is loaded, if a CONFIG.SYS file is present in the diskette directory, 
the number and range of allowable open LFN's, the number and type of disk drives, 
whether ISAM (Indexed Sequential Access Method) routines are to be active in the 
system, and the number of ISAM and sequential file buffers present in the system are 
set according to the control lines in the CONFIG.SYS file. 


In addition, if the multi-communications option is in the system, the MCOM1 to MCOM4 
control lines of the CONFIG.SYS file set the baud rate, parity, byte length, stop bit 
length and transparency mode for each of the four ports. 

Example: 


CONFIG.SYS 


(lines beginning with an asterisk * are remarks) 


ee & & 


FILES OF=15 SB=6 

ISAM OF=7 IB=3 DB=3 

DISKS U0=S U1=S 

MCOM1 BAUD=9600 STOP=1 PARITY=EVEN LENGTH=7 TM=N 
MCOM2 BAUD=300 STOP=1 PARITY=EVEN LENGTH=7 TM=Y 
MCOM3 BAUD=9600 STOP=1 PARITY=EVEN LENGTH=7 TM=N 
MCOM4 BAUD=9600 STOP=1 PARITY=EVEN LENGTH=7 TM=N 


If a CONFIG.SYS file like the example were present when the system was loaded, the 
system would contain nearly 40 kilobytes of user memory area (approximately 20 
kilobytes of the 40 would be needed for RUN). 15 open files would be allowed, with 
up to 7 open ISAM files. Up to 6 sequential files would be allowed open simultaneously. 
3 ISAM index and 3 ISAM data buffers would be reserved. Two single sided disk units 
would be active, numbers 0 and 1. Four multi-communications ports would be active, 
three of them (numbers 1, 3 and 4) operating at 9600 baud with a single stop bit, 
even parity, 7-bit bytes, in non-transparent mode. One port, number 2, would operate 
at 300 baud in transparent mode, with the other characteristics the same. 


Table 1-1, System Configuration Controls, and Table 1-2, Configuration Default Values, 
list the meaning and memory costs of the CONFIG.SYS control lines and the default 
value if a CONFIG.SYS file is not used. The types of control lines are discussed 
briefly below: 


* Remark lines begin with an asterisk at the left margin. Remarks serve 
to document the file, but do not affect the configuration of the system. 


ee 


1.1 CONFIG.SYS SYSTEM 


FILES Only a single line with FILES at the left margin is allowed. The FILES 
line specifies the total number of open files (sequential and random each 
count as 1 file; each ISAM counts as 2 — 1 data and 1 index file). The 
FILES directive also specifies the number of sequential buffers. Each 
open sequential file requires a buffer. Memory requirements are 24 
bytes for each LFN and 512 bytes for each sequential buffer. If the 
COMPILE compiler is to be used, at least 3 sequential buffers must be 
specified (6 if all options are used). Default values (if no CONFIG.SYS 
file present) are 24 open LFN's and 6 sequential buffers. The minimum 
allowed in the FILES control line is 1 LFN (OF=1) and 0 sequential 
buffers (SB=0) 


ISAM If the ISAM line is not present in the CONFIG.SYS file, no ISAM routines 
will be resident in DX-85M and no ISAM access will be allowed. The 
ISAM routines occupy approximately 6200 bytes. If an ISAM line is 
present, only one is allowed. The ISAM line control groups specify the 
number of open ISAM files allowable (counting each file as 1; that is, 
each index-data file pair as 1 ISAM file), and the number of index and 
data buffers available. ISAM access times can be speeded substantially 
if additional index buffers are available for large ISAM files; access 
speed for files with large records can be increased by additional data 
buffers. Memory requirements are 80 bytes per allowable open ISAM 
file and 521 bytes per buffer. Default value is no ISAM. Minimums 
allowed in the control groups if CONFIG.SYS and the ISAM line are used 
are 1 open file, 2 index and 1 data buffer (OF=1 IB=2 DB=1). a, 


DISKS Disk drive units which will be used must have their type declared if 
CONFIG.SYS is present. Each unit must be specified as type S (single- 
sided diskette, followed by an optional physical address), D (Double-sided 
diskette, followed by an optional physical address), HX for 14 inch 12 
and 24 megabyte fixed disks formatted with a 1:1 interleave or FX for 
14 inch 12 and 24 megabyte fixed disks formatted with a 15:1 interleave. 
To specify the 5-1/4 inch fixed disk, enter Itpd, (refer to table 1-1). If 
single-sided disks are to be read on a double-sided drive unit, the drive 
unit must be declared single-sided. It will then act as a single-sided 
drive until the system is re-booted and a new configuration specified. 
Single-sided drives must not be declared double-sided, however. A drive 
unit which will not be used need not be declared. Memory requirements 
are the same in any case: disk drive declaratives take no memory space. 
Default values (if CONFIG.SYS is not present) are four single sided or 
four double sided drives, unit 0 through 3 (U0=S P or DP U1=S P or 
DP U2=S P or DP U=3S or DP). At least one disk drive must 
be declared if CONFIG.SYS is present. 


NOTE: The optional physical address number (P) following the disk type 
specifier S or D, is primarily used in a one diskette system, with no 
unit 1, and an auxiliary diskette unit attached. If no "P" is specified, 
the system will automatically assign the physical addresses in sequence, 
starting with 0. 
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MCOMn If the multi-port serial interface is present, lines beginning with MCOMn, 
where n is an integer between 1 and 4, specify the properties of each 
I/O port: the baud rate, parity, length of byte and length of stop bit, 
and transparency mode. Legal baud rates range from 50 to 19200; parity 
may be odd, even or none; stop bits may be 1, 1.5 or 2; byte length 
may be 5, 6, 7 or 8 bits; and transparency mode may be on (TM=Y or 
TM=YES) or off (TM=N or TM=NO). 


NOTE: No MCOM lines should appear in CONFIG.SYS files used with 
systems without the multicommunications options, since the attempt to 
initialize a nonexistent communications port causes a bus timeout error 
which prevents completion of the system loading routine. If this should 
occur, a disk not containing a CONFIG.SYS file with MCOM line must 
be used to load an operating system; FILES can then be used to delete 
or rename the CONFIG.SYS file with the MCOM lines, to allow use of 
the diskette on the F-85 without the multicommunications option. 


STOP The last line of CONFIG.SYS may have STOP at the left margin, followed 
by at least one space and at least one other character. STOP HERE 
is a typical example. If a STOP line appears, the system will display 
the CONFIG.SYS file and the amount of free memory when the system 
is loaded. If the STOP line does not appear, the CONFIG.SYS file will 
be flashed on the screen, immediately replaced by the system startup 
message. 


Each line in CONFIG.SYS must have * FILES ISAM DISKS STOP MCOM1 MCOM2 
MCOM83 or MCOM4 at the left margin or an error will occur. A line containing an 
error generates an error message at system loading and the attribute controlled by 
that line is given its default value. Control groups on a directive line are separated 
from the directive and other control groups by one or more spaces. 


In MCOM directive lines, keyword groups with illegal or senseless values are given 
their default values, but the rest of the line will be used where legal. 


CONFIG.SYS ean be written with the EDIT utility (see Subsection 1.2 for a discussion 
of EDIT use) or generated with the CONFIGURE utility (see STAR BASIC Utilities 
Reference Manual). 


1.1 CONFIG.SYS 


Directive 
Control Group 


FILES 


OF=number 


SB=number 


ISAM 


OF=number 


IB=number 


DB=number 


Table 1-1, System Configuration Controls 


Effect 
Minimum Required 


remark symbol; lines beginning 


with an asterisk are documentary 


Open Files: maximum number 
of LFN's allowed 


OF=1 
Sequential Buffer: maximum 
number of sequential files 
open at once 


SB=0 


ISAM files: keeps ISAM 
routines active in system 


Open Files: maximum number 
of ISAM files open at once 


OF=1 


Index Buffer: number of index 
buffers in system 


IB=2 


Data Buffer: number of ISAM 
data buffers in system 


DB=1 


SYSTEM 


Memory Cost 


(bytes) 


24/file 

24 
512/buffer 
0 

6144 
80/file 


80 


521/buffer 


1042 


521/buffer 


921 
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SYSTEM 1.1 CONFIG.SYS 
Table 1-1, System Configuration Controls 


DISKS 


Unumber=letter [P] number=disk unit number 
letter =S single-sided diskette 

= double-sided diskette 

=[P] optional physical address number (0 to 3) 

=H1 14 inch 12-megabyte fixed disk 
(Formatted 1:1 interleave) 

=H2 14 inch 24-megabyte fixed disk 
(Formatted 1:1 interleave) 


=FX 14 inch 12-or 24 megabyte fixed disk 
(Formatted 15:1) 


12_ megabyte 24 megabyte 
X=O 1st 12m 1st half (12m) 


1st direc. 1st 24m 


X-1 N/A 2nd half (12m) 
2nd diree. 1st 24m 


x=2 2nd 12m 1st half (12m) 
1st direc. 2nd 24m 


x3 N/A 2nd half (12m) 
2nd diree. 2nd 24m 


=Itpd 


I, specifies 5 1/4 inch fixed disk 

t, 5 1/4 ineh fixed disk type 

t=A, 7Mb version 

t=B, 14Mb version 

t=C thru P, reserved 

Pp, physical disk drive address 

p=0 integral 5 1/4 inch fixed disk 

p=1 auxiliary 5 1/4 inch fixed disk 

d, 5 1/4 ineh fixed disk directory number 

d=0 ist directory, 1st half of 14Mb 5 1/4 inch FD 
d=1 2nd directory, 2nd half of 14Mb 5 1/4 ineh FD 


NOTE: The "t", type designator letters, will be assigned in the range "A" to "Pp" 
inclusive. The letters are used to define factors such as, number of heads, number 
of cylinders, seek rate, etc. The physical driver address "p" is optional, unless a "d" 
number is defined, then the physical address is required. Default phvsical address will 
be 0. The optional directory number "d" is only necessary on large capacity 5 1/4 
inch disk drives with two directions. Default for the directory number is 0. 
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1.1 CONFIG.SYS 


Locations 


Table 1-0, Physical Drive 
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SYSTEM 1.1 CONFIG.SYS 


Table 1-1, System Configuration Controls 


MCOMnumber 1 = number =4 


BAUD=number _ Baud rate (bits/second) 
number=50, 75, 110, 134.5, 
150, 300, 600, 1200, 1800, 
2000, 2400, 3600, 4800, 
7200, 9600, or 19200 


STO P=number number of stop bits 
number= 1, 1.5 or 2 


PARITY=string type of parity 
string=EVEN or ODD or NONE 


LENGTH=number length of byte 
number=5, 6, 7 or 8 bits 


TM=string transparency mode 
string=Y or YES or N or NO 


Table 1-2, Configuratuion Default Values 


FILES OF=24 SB=6 
DISKS U0=S P or DP U1=S P or DP 
U2=S P or DP U3=S P- or D P 


If no CONFIG.SYS file is present at system load time (CODE LOAD), default is no 
ISAM, no multi-communications ports, 24 files, 6 sequential file buffers and four single 
sided diskette drives, or double sided diskette drives. If one or more MCOMn lines 
are present, the multi-communications port defaults will be: 


MCOMn BAUD=9600 PARITY=EVEN STOP=1 LENGTH=7 TM=N 


The multi-communications default values apply to any keyword group not (or incorrectly) 
specified. 


NOTE: MCOM lines must not be used in systems without the multicom option. These 
lines must be converted to remarks (add an * at the left margin) or the CONFIG.SYS 
file must not be used (remane or delete it) before the disk is used for code load, since 
an attempt to initialize an nonexistent multicom port causes a bus timeout error which 
prevents completion of the system loading routine. 


1.2 EDIT 


definition: | EDIT invocation 
EDIT [/unit number][ *] filenamei[/unit number ][,filename2 [ /unit number ] ] 


The EDIT utility writes and edits program source files. It is invoked by inputing EDIT, 
a filename and possibly some optional expressions after the system command prompt. 


unit number = integer indicating disk unit bearing file (default is unit 
0) 
filenamel = input filename (also output filename if filename2 not 


used; input file then becomes filenamel- to indicate 
backup file) 


filename2 = output filename; default is filenamel with input file 
being renamed with a - appended to indicate backup 
status 

* = if used, causes video display in large font (16 lines 


by 64 characters); default is small font (24 by 80) 


The first character of a filename must be an alphabet character. Filenames can be 
up to 10 characters long. Any printable character may be used following the first 
(alphabetic) character, but use of blanks, commas, slashes, question marks and _ asterisks 
will interfere with operation of the FILES and COPY utilities and should be avoided. 


EDIT can be used to create new files or to edit existing source files. If the * is 
used, any line longer than 64 characters will be truncated. Programs edited without 
the * should not be re-edited with the * or errors because of truncation may occur. 
If the output filename is not designated and a backup (ending in -) of the input file 
already exists, the old backup is deleted and the input file becomes the new backup. 


Editing is performed on ASCII data within the EDIT data buffer on a FIFO (first in, 
first out) basis. The input file (if any) is read into the buffer as directed by EDIT 
controls and commands. When the buffer is filled and more data is read in, the excess 
is written to the output file on the designated diskette. Once a line passes beyond 
the top of the screen, in other words, it cannot be edited further unless the current 
edit is ended and a new edit is begun. 


A number of EDIT controls are active during cditing. In addition, a number of 
commands are available in the EDIT command mode, which is signified by the $ prompt. 
Table 1-3 defines the EDIT controls, commands, and error messages. Although editing 
and creation of source programs is the primary use of the EDIT utility, any ASCII file 
ean be created with this utility. 


Examples: EDIT Invocation 


:EDIT * NAME.SRC 
:EDIT PROGRAM.S,NEWPROG.S 
:EDIT * MOD1.BAS/1,MOD2.BAS 
:EDIT/1 PROG.BAS/4 


SYSTEM 


1.2 Edit 


Table 1-3, EDIT CONTROLS, COMMANDS AND ERROR MESSAGES 


Edit Commands (to $ prompt) 


E 
End successful edit, write output file and 
close truncate. 


A 
Abort edit, delete output file. 


Pfilename [/unit ,string ] 

Position named file (from unit if not on 
unit 0) at the first instance of string; 
RETURN brings back file being edited, 
(down arrow) scrolls through file being 
searched; may be used on input file or any 
other file, to obtain line numbers or inspect 
source. 


Gfilename [/unit ],number1,number2 

Get lines from physical line number1 
through number? from file filename (on unit 
if not on unit 0), insert in file being edited 
just after last line on screen with last new 
line at bottom of screen. 


TC Clear tab stops (stop at column 6 is 
automatie on entering EDIT). 


TA 
Assembler tab: clear tabs, set new stops 
at columns 9, 15 and 30. 


Fstring 
Find the first instance of the search string 
in the input file, position that line at 
bottom of screen; leave rest of screen 
blank. 


Sstring 

Search for string at left end of lines 
below screen (used for fast searches for 
line labels); position that line at bottom 
of blank screen. 


R/string1/string2[/A] 

Replace string] with string2 from line 
just below screen to end of file; optional 
/A at end of command orders all 
replacements automatically; if A is not 
used, operator must give a Y to prompt 
for each line to replace: ESC (abort, only 
in R. command) at prompt ends the entire 
EDIT and leaves the file as it was 
previous to the EDIT run. 


Lnumber 

Move input file to physical line number; 
line number will be at the bottom of a 
blank screen. 


Knumber 
Delete the next number of lines, starting 
at the line at the bottom of the screen. 


Tnumber 
Sets tabs at column number and every 


number thereafter, where number is an 


integer between 1 and 9; (T3 sets a tab 
at columns 3,6,9,12,15 and so on). 


U 

Upper case toggle: toggles the reverse 
alpha shift of the keyboard; used for the 
first time, it results in a normal 
typewriter shift for alphabet characters; 
used again alpha shift is reversed. 


EDIT begins in normal editing mode, with the first line of the input file just below 


the screen. 


The (down arrow) key will scroll lines onto the screen (and off the top, 


to the output file, when the screen is full) if it is at the bottom left corner of the 


screen. 


Cursor controls only move the cursor they DO NOT generate blank lines in 


program text. To enter command mode, press the ESC key. The $ prompt will appear 


at the lower left corner with the cursor beside it. 


Enter the command as shown above 


and press RETURN, or use CODE C, and EDIT returns to normal editing mode. 
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Table 1-3, EDIT CONTROLS, COMMANDS AND ERROR MESSAGES (Cont'd) 


EDIT Control Keys 


(left arrow) 
Move cursor left. 


(right arrow) 
Move cursor right. 


(up arrow) 
Move cursor up. 


(down arrow) 

Move cursor down; if at lower left corner 
of screen, scroll on new line. Cursor DOES 
NOT create blank lines in program. 


CODE (down arrow) 
Move cursor to lower left corner of screen 
("home"). 


ESC 
Enter command mode (give $ prompt at 
lower left with cursor alongside). 


EDIT Error Messages 


EOF ON INPUT FILE 
End of file reached on the input file (L,F, 
S and K commands). 


EOF ON GET FILE 
End of file reached during G command. 


EOF ON POS FILE 
End of file reached during P command. 


EOF ON OUTPUT FILE 
Not enough disk space. 


PARAMETER ERROR 
Error during EDIT invocation, or 
syntax of a command. 


in the 


INVALID FILENAME 
File name is too long, or contains illegal 
characters, or is otherwise invalid. 


NO INPUT FILE 
Input file not found on disk unit specified. 
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DEL 
Delete character at cursor. 


CAN or CODE X 
Cancel characters on cursor line; if 
cursor is at left end, cancel line too. 


CODE Z 
Add blank line at cursor, move line at 
eursor and above upward. 


CODE T 
Set tab stop at cursor. 


TAB 
Move cursor to next tab stop to right. 


CODE C 
Cancel EDIT command mode, 
normal editing mode. 


resume 


OUTPUT FILE IS WRITE-PROTECTED 
Specified output file is marked as write- 
protected in its $DIRECTORY entrv. 


OPEN ERROR ON OUTUT FILE 

Error occurs during attempt to open 
output file: EDIT.TMP temporary output 
file may be left on diskette. 


DISK READ ERROR 
Error during attempt to read file. 


DISK WRITE ERROR 
Error during attempt to write file. 


CLOSE ERROR ON INPUT FILE 
Error during attempt to close input file. 


CLOSE ERROR ON OUTPUT FILE 


Error during attempt to close truncate 
output file. 
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Table 1-3, EDIT CONTROLS, COMMANDS AND ERROR MESSAGES (Cont'd) 


INVALID LINE NUMBER 

Line number specified is not an integer, 
is out of range, or is previous to present 
position (L command). 


INVALID NUMBER 

Number of lines is not an integer, is out 
of range, or otherwise illegal (K 
command). 


INVALID LINE NBR 
G (Get) command physical line number is 
not legal. 


OPEN ERROR ON GET FILE 

Error during attempt to open file for 
insertion of material with the G ‘Get) 
command or the P (fPosition) command. 


INVALID STRING 
Search string is not legal (P command). 


INVALID COMMAND 

Command is not legal command, is syn- 
tactically illegal, or is otherwise ill- 
formed. 
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1.3 COMPILER USE 


definition: COMPILE invocation 


: COMPILE [/unit] source filename[/unit][ compiler parameter list ] | 


definition: compiler parameter list | 


[O=filename [/unit ]][,L=* or filenamef /unit] ][ ,OPT=option string][,LIB=filename[/unit}} 


CAUTION: The Format changes in Compile generated Star Basic object Code, 
necessitates the re-compilation of all existing Star Basic programs. The programs will 
then be able to run under DX-85M release 2.5 operating system. The re-compiled 
object code (under release 2.5) is not compatible with previous release compiler outputs. 


Note: The following parameter keywords are freely interchangeable: 


OBJECT or OBJ or O 

LISTING or LIST or L 

OPTIONS or OPTION or OPT a 
LIBRARY or LIB 


The OBJECT keyword group specifies an object file name if used; default is the source 
name with .OBJ appended. The LISTING keyword group specifies the list filename; 
an * specifies the video display screen; default is printer output. The OPTIONS keyword 
group allows one or more compiler options to be specified; see Table 1-4 for details 
and default values. The LIBRARY keyword group allows a file to be specified as a 
routine library; routines from the library will be copied into the output program by 
the compiler as specified by COPY statements in the STAR BASIC program being 


compiled. 

Element Meaning Example 

H system command prompt 

COMPILE compiler program name 

source filename name of the source program PROGFILE 
file (created through EDIT) ARPMEN.B 

/unit designates disk unit bearing PROGFILE/1 
(or to bear) file to which COMPILE/1 
/unit is attached; RAS.OBJ/0 


default is unit 0 
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Element Meaning Example 
filename legal file name to be given to list PROGFILE.L 

or object code file, or the name ARPMEN.L 

of a library file; list file defaults ARPMEN 

to hardcopy listing; object code ATFL.O 

filename defaults to adding .OBJ BASIC.LIB 

to the source filename; library TAX.L 


filename defaults to no library TAX.O 
file specified 


* or filename * causes listing to be shown on L=* 
the video display; filename causes L=LSTFL 
creation of a list file with that L=PROG.L/1 
name; if list keyword not used, list 
is output on printer 

option string one or more of the optional OPT=E 
control characters PSNECKXL OPT=N 
(see Table 1-4) OPT=SCX 


The compiler program, COMPILE, is used to convert source code programs created 
through the EDIT utility to object code programs which run under RUN. In its simplest 
form, the COMPILE invocation is as follows: 


: COMPILE PROGNAME 


where both COMPILE (the compiler program) and PROGNAME (the program to be 
compiled) are on disk unit 0. (The : is the system command prompt.) A /0 or /1 
(or, in systems with auxiliary drives, /2 or /3) can follow any filename to indicate 
that the file is on drive 0 or 1. The disk unit designator is always optional, defaulting 
to unit 0. 


An optional parameter list may follow the source filename, if desired. It must be 
separated from the source filename by a space, and each item on the list must be 
separated from each other item by a space. Commas may replace the spaces as 
separators, if desired (and commas and spaces must not appear in filenames or errors 
will result). 


If the optional parameter list is used, keywords designate the various parts of the list. 
OBJECT= or OBJ= or O=, followed by a filename, can be used to specify the name 
(and disk unit, if the filename is followed by a /number) of the object code file. 


If the object file name is not specified, the compiler creates an object file name by 
truncating the source file name at the first period . and adding .OBJ. If there is no 
period in the source file name, .OBJ is added to the end of the source name (if the 
source name is 6 characters or less). If the source name is longer than 6 characters, 
it is truncated at position 7 and .OBJ added. 
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Examples: 
Source name Object name 
PROG.SRC PROG.OBJ 
TRU.OR.FAL TRU.OBJ 
AP3 AP3.OBJ 
PROGFILE17 PROGFI.OBJ 


LISTING= or LIST= or L=, followed by an asterisk * or by a filename (the filename 
may be followed by a /number designating disk unit), may -be used to designate the 
listing destination. Default is a hardcopy listing on the system printer. If the * is 
ised, the listing will be displayed on the video; if the filename is given, a list file 
vill be created on disk. 


IPTIONS= or OPTION= or OPT=, followed by one or more of the option control 
vharacters (PSNECXL), may be used to control the range of the listing or suppress 
xbject code production. Table 1-4 shows the meanings of the various control characters. 
Any single character, or any combination of characters, may be used. The option 
parameter defaults to print source lines and symbol table, do not print code or 
cross-reference. 


Table 1-4, STAR BASIC Compiler Options 


Option Meaning 
Symbol 
P Program: suppress printing of source lines, print only error lines and 
symbol table; default is print source lines 
s Symbols: suppress printing of symbol table; default is print symbol 
table 
N Nothing: suppress printing of source program lines and symbol table; 
default is print source code lines and symbol table 
E Errors: suppress allocation of object code, and scratch files. If 
object file already exists, it is not deleted. 
Cc Code: print object code interspersed with source code lines; 
default is no object code printed 
K Compressed: print listing using compressed font (small type); default is 


large font 
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Table 1-4, STAR BASIC Compiler Options (cont'd) 


Option Meaning 
Symbol 
X X-Reference: print cross reference listing showing where variables and 
arrays are used in program; default is no cross reference 
table printed 
L LABEL: includes statement labels in the symbol table listing when 


used with X-Reference, the line where the label is defined 
is listed along with the other references. 


Object code file generation is automatically suppressed when an error is detected 
during a compilation. 


The keywords in the parameter list may be used in any of the forms shown. Any one 
keyword may be used only once in an invocation. The various forms of the keywords 
a may be mixed, as illustrated by the examples below. 


Examples: 


: COMPILE PROGFILE OBJECT=PROG LISTING=PROG.L OPTIONS=X LIBRARY=BASIC.LIB 
: COMPILE/1 ARPMEN/1 OBJ=ARPRUN/0O LIST=ARPLST/1 

: COMPILE TAX.S L=* OPT=NXE 

: COMPILE TAFRDC O=TAFO/1 L=* 

: COMPILE RADFLS L=RADLST LIB=BASIC.LIB/1 

: COMPILE NOMRST OPT=NC 

: COMPILE POSROM O=POSRUN LIST=POSLST OPTIONS=X 


The C option is used by systems programmers to aid in developing the compiler. Since 
the source listing becomes quite difficult to read and the listing is substantially longer 
when the C option is used, while the object code is nearly unreadable to anyone other 
than systems programmers, applications programmers are unlikely to use the C option 
more than once. 


COMPILE opens three to six sequential files during operation: the input file the 
source program), the output object file, a scratch file, and optionally, a list file, a 
cross reference file, and a library file. The list, cross reference and library files are 
used only when the parameter list calls for their use. 


DX-85M must be configured to include enough sequential buffers and open files when 

COMPILE is invoked or an error will result. The default configuration (no CONFIG.SYS 

file) includes 24 open files and 6 sequential buffers, so the full compilation with library, 
a listing and cross reference files is possible in that configuration. See Subsection 1.1 
ww for a discussion of system configuration. 
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In additon, there must be enough disk space free to allocate needed files. The object 
code file is allocated first, requiring 70 blocks of continuous free disk space. (It is 
close truncated after compilation.) The scratch file requires 150 blocks (it is close 
deleted before termination). Cross reference files require 20 blocks (and are close 
deleted. List files are allocated to take the largest amount of free space left on the 
disk, and are close truncated. 


The object code file is allocated first, followed by the scratch file, the cross reference 
file (if any) and the list file (if any). The object files disk unit may be specified if 
an object file name is specified; if the .OBJ default object code file name is used, it 
will be allocated on the same unit as the source file. 


The seratch file and cross reference file will be allocated on the same unit as the 
object file. List and library file locations are specified in their control groups. 


The simplest invocation (no files specified except the source) requires 220 blocks free 
on the source disk, 70 for the object file and 150 for the seratch file. If cross 
reference or a list file are required, the appropriate amount of additional disk space 
will be needed. 


Program Size Limits 


Program size is limited by the following factors: the amount of user space available 
at runtime, the size of the scratch and output files, and the size of the compiler's 
symbol table during compilation. 


The amount of user space available at runtime varies according to the system 
configuration. The maximum user space in a practical configuration (only 1 file allowed 
open at any time, no sequential buffers, no ISAM or ISAM buffers, two single sided 
disk units) yields 148 pages, or approximately 37 kilobytes, of user space after RUN 
is loaded. Typically, systems including a number of sequential buffers, ISAM and ISAM 
buffers, and allowing 10 to 20 open files yield about 120 pages of user space. A page 
is 256 bytes. 


The amount of user space needed to run a program is given at the bottom of the 
compiler listing, and in a video message. The space requirement figure given includes 
5 pages of stack space—larger amounts of stack space may be needed if very large 
strings are handled, or if a large number of gosub's and call's are issued. 


The scratch file is used to hold a schematic version of the object code, which is then 
assembled and written to the object code file. The size of the object code file is 
the most limiting factor. The 70 block object code file allocation allows programs 
with up to approximately 30 kilobytes (118 pages) of object codes. 


Code size is determined by translating the last action line address in the compiler 
listing of a program to decimal and dividing by 256. Thus, if the last line of the 
program is at 12EB, it is 4843 bytes long, slightly less than 19 pages. When the 
program is run, the additional space for variable storage and stack will be required, 
but this space is not needed in the object code file. 
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The compiler's symbol table lists each label and name used in the program. Symbol 
table size varies as a function of the length of the symbols, so exact estimates are 
difficult. Also, the amount of space available for COMPILE to use varies according 
to the system configuration, also complicating allowable size calculation. 


Using the default configuration of the system, there is enough symbol table space to 
hold approximately 1,600 two character names and labels, or about 1,000 names and 
labels averaging 10 characters a piece. In a system configured with ISAM, this is 
reduced to about 1,000 two character names and labels, and about 750 when average 
size is 10 characters. 


In addition, the compiler's code efficiency decreases if there are more than 256 variable 
names used in a program. Programmers are therefore urged not to use unnecessary 
line labels, as this wastes symbol table space, and to use arrays where possible if more 
than 256 varying values are to be manipulated. 


Few well-written programs approach the compiler's limits. The most common limiting 
factor is the size of the user space. The symbol table limit could be a factor in very 
long programs, but is not normally a program as long as unneeded labels are not used. 


1.3 Compiler Use 


Durango STAR BASIC 


EXPAND.E 


OAFE 
ONE 
ONAL 
DAAA 
Ove 
O4R9 
O4ct 
O4AC1 
0401 
0407 
CUteys) 
@ADe 


SYSTEM 


Figure 1-1, Default Compiler Listing 


Routine Listing 


Language Release and version number 
‘a Title, if any a Date and Time 
Nelease 2.5 

EXPAND !-- DO ‘COPY’ PROCESSING FROM MULTIPLE LIBRARTES Page number \ 
168 PARSE: | PARSE FILENAME/UNIT IN LINE®, PUT UNIT IN ’U’ 03/16/82 14210811 Page 4 
169 u=0 
170 P = POS(LINE$,"/") 
171 IF P > @ THEN 
172 U = LINES(P+1) 
172 LINE$ = LINE$(19P-1) 
174 ENDIF 
175 LINES = LINES & " as 
176 LINES = LINE®(1510) Source listing 
177 RETURN 
178 
179 END 


= Physical line numbers 


Memory location 


Input Filename 


Symbol Table 


Variable or array names or labels 


Durango STAR BASIC Release 2.5 03/16/82 14:10:21 Page 5 
EXPAND .B 
Variable Location peTrenuees Descriptor location 
BOOK. START eS pe Fined A * ety Sus inked és Date location 
, xe rra ou u . . . 
<i a toe ee ee Fi wrny Osby wnncigted ta] Variable's characteristics 
CUR. LINE @535 1CED 
CURFILES @512 1CFS Array 10 
EDT$ 0504 iCFF Array 5 
FILENAMES @4EB 1004 Fixed Array Doubly Subscripted 4000 
1 @54A 2CA4 
K @56D 2CAC 
HATN(9990)? 16% symbol table used —<—_________ Starting location of routine (MAIN), 
Code 1242, variables 149230. common ®, no errors | percent of memory used for symbol table. 
469 pages program, NO Common storage required Number of errors found. 
Amount & storage required (in bytes) 
for this routine's (MAIN's) code 
(program statements), variables, and 
common. 
Size of common memory area required. 
Amount of memory required to run a 
program (includes 5 pages for stack 
overhead). 
1-20 
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1.4 RUNX 


definition: RUNX invocation 


: RUNX [/unit] Partition Control filename [ /unit ] 
Module list filename [/unit] 


Element Definition 

: system command prompt 

RUNX program name 

Partition Control the name of the partition control file or the 
Filename number of COMMON pages. 

Module List Filename the file containing the list of optional system support 


modules to be loaded. 
[unit ] | unit in which program resides (default to unit 0). 


RUNX will load optional system support modules, specified in a Module List File, into 
the computer memory. Once the system modules have been loaded into memory, they 
are locked in. If another program, other than RUNX, is selected the memory space 
occupied by the modules will not be available. To free this memory space, the memory 
must be cleared by a CODE LOAD (holding the CODE key down and depressing the 
LOAD key). 


NOTE: Multiple invocations of RUNX will duplicate the module list file. This can 
cause available user space to become smaller. 


RUNX has two parameters, as shown in the list above. The first parameter is the 
same parameter as would normally be given to RUN or RUNB, which is the name of 
the partition control file (or the number of COMMON pages). The second parameter 
is the name of the file containing the list of optional system support modules to be 
loaded. 


When the Module List File is created it should follow the form shown below: 


first module name [/unit ], [parameters ] 
second module name [/unit ], [parameters ] 
ete. module name [/unit ], [parameters ] 


RUN(B) /unit 


The parameters allow the operator to provide specific module initialization information. 
The last line indicates to RUNX whether RUN or RUNB is to be executed after RUNX 
completes the loading of the modules specified. The optional unit specification indicates 
where the module or program resides (default is unit 0). 
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1.5 RUN-TIME MONITOR USE 


definition: RUN invocation 
RUNB invocation 


: RUN [/unit ][control filename [/unit ]][numbers ] 
: RUNB[/unit |[control filename [7unit ] [numbers] 


Element Meaning 


system command prompt 


RUN runtime program name 


control filename control file defining partitions in multi-user 
mode; (see Subsection C.J for multi-user proce- 
dures); defaults to single user mode (filename 
must not be used if multi-user option is not 
required) 


number specifies number of pages of COMMON memory 
required; may not be used if partition control 
filename is used; 

/unit 

_— number designating the disk unit bearing the 
program to which /unit is attached (i.e., RUN/1 
gets RUN from unit 1); default is unit 0 


RUN is a STAR BASIC runtime monitor. RUN operates in both single-user and 
multi-user modes. The appropriate hardware option is required to use the F-85 and 
RUN in multi-tasking mode. See Appendix C for a discussion of multi-user procedures. 
RUNB is a STAR BASIC runtime monitor. RUNB operates primarily as a multi-user 
utility. The appropriate hardware options (5MHz CPU plus the Memory Expansion 
board) are required to use RUNB with the release 2.5 operating system. Note that 
earlier operating systems only require the 5MHz CPU option. It can also function as 
a single-user. Refer to Appendix C for discussion of multi-tasking user procedure. 


NOTE: Any reference, in the manual, to RUN, stands for RUN or RUNB run-time 
monitor, whichever the user has selected, unless specified. 


After invocation, RUN returns the * command prompt. If a filename of an object 
code file is input, RUN will load and run that program. If the LOAD command is 
given, RUN will load the program and breakpoints can then be set with the BREAKPOINT 
command. After a program is loaded, a RUN or GO command will start execution, 
RUN only at the beginning, GO from any current position. The DISPLAY command 
will display variable's values. The QUIT command ends RUN execution. 


definition: Load and Go (RUN) 


* filename [/unit] 
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If a filename of a STAR BASIC object code file (resulting from the compilation of a 
STAR BASIC source program) is given to the RUN command prompt (the asterisk * ), 
the program will be loaded and run. 

Filenames beginning with the two letter RUN commands are acceptable. Therefore, 
GO, RU, QU, BR, DI or LO at the beginning of an object filename will retrieve the 
file. The RUN commands, in the load and go mode, must be entered as two letters 
followed only by a space, a comma, or a RETURN. 


definition: LO command (RUN) 
* LO,filename[/unit ] 


To load an object code program, after the RUN prompt * , input the command word 
LO followed by a comma or a space, followed by the name of the object code file, 
optionally followed by a slash / and the unit number of the disk containing the object 
code file. RUN will again return the * prompt. 


definition: RU command (RUN) 

* Ro 
To run a loaded object code program, input RU after the * prompt. This command 
may be used only to run a newly-loaded program (one which has not yet been run). 


definition: GO command (RUN) 


* GO 


NOTE: In RUNB only, the GO command is used to continue with a program only after 
a BR (breakpoint). It will not work after a LO (load). 


To run a loaded object code program from the current position (as, after a breakpoint: 
see below) input GO after the command prompt *. RUN will always run the loaded 
program from the beginning; GO will always run the loaded program from the current 
position (which may be the beginning, or may be elsewhere if a breakpoint halted 
previous execution). 


definition: QU command (RUN) 


* QU 


To leave RUN and return to the system command level (: prompt) input QU after the 
RUN command prompt *. Note: This command cannot be used in multi-user mode. 
See Subsection C.1. 
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definition; BR command (RUN) 


* BR location number 


To set a breakpoint in a loaded object program, input (after the RUN command prompt 
*) BR followed by a space followed by the location number of the line where the 
breakpoint is desired (from the program's compiler listing). If the optional location 
number is not used, this command clears all breakpoints. 


definition: | DI command (RUN) 


* DI location number 


To display the value of a variable or a single dimension string array, input (after the 
RUN command prompt *) DI followed by the hexidecimal descriptor location of the 
variable (from the compiler listing symbol table). 


To display a two dimension string array or a single dimension numeric array, input DI 
followed by the descriptor location followed immediately by the subscript number of 
the desired string enclosed in parens. 


To display a two dimension numeric array, use the procedure for a single dimension 
numeric array, counting the subscripts serially. Thus, a 2 by 10 numeric array could 
be displayed: 


* DI 0C77(1) displays Array(1,1) 
* DI 0C77(2) displays ~  Array(1,6) 
* DI 0C77(10) displays Array(2,5) 


* 


DI 0C77(11) displays Array(2,1) 
and so on. 


String values are displayed enclosed in quotes: "value". Numeric values are displayed 
as in PRINT statements. 
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1.6 $AUTOSTART 


$AUTOSTART is the turnkey applications system control file. The names of programs 
to be loaded and run are held in $AUTOSTART, which acts as if it were keyboard 
input when the system is loaded (CODE LOAD). $AUTOSTART is created by the 
applications programmer, using the EDIT utility. 


When creating the $AUTOSTART file the user may specify the date format, also the 
date and time prompting. Lines are processed from the beginning of the file until a 
non-control line is read. Control lines are defined by the first two characters; the 
first character is always "$". Control line identifiers, with the second character in 
either upper or lower case, are: 


"$D" - the following text is for the date entry prompt, date is to be entered 
in the format DDMMYY; 

"$M" - the following text is for the date entry prompt, date is to be entered 
in the format MMDDYY; 

"$Y" - the following text is for the date entry prompt, date is to be entered 
in the format YYMMDD; 

"$T" - the following text is for the time entry prompt, time is to be entered 
in the format HHMM, as always; 

"$E" - the following text is for the illegal date entry error message; 

"$U" - the following text is for the illegal time entry error message. 


Control lines may have up to 48 characters of text following the two character 
identifiers, the system will append three blanks and erase to the end of the line when 
the text is displayed. The limit for non-control information (such as utilities, programs 
ete.) is 40 characters, including a carriage return at the end of each line of text. 
The date format within the system, accessed by the STAR BASIC "DTE$" function, 
put on compiler listing ete., is still in MMDDYY format no matter which is used for 
its entry. In multi-user modes, $AUTOSTART contains a single line: RUN followed 
by the name of the partition control file (see Appendix C). In single user mode, 
$AUTOSTART contains two lines: RUN alone on the first line, the name of the 
program to be loaded and run on the second line. 


The $AUTOSTART file may contain up to 40 characters. 
Examples: 


Single user mode: RUN 
TACK 


Multi-user mode: RUN PART 


In the examples above, RUN is of course the run-time monitor. "TACK" is the name 
of the program to be run. PART is the name of a partition control file. 


On CODE LOAD, after the CONFIG.SYS file (if any) has configured the system and 
the startup system routines are complete, if there is a $AUTOSTART file in the 
diskette directory in unit 0, the date and time will be set and the contents of that 
file will be treated as keyboard input. 
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1.7 BATCH 


definition: BATCH invocation 


: BATCH[/unit] input filename[/unit] [output filename [/unit ]] 


The BATCH utility allows unattended use of the F-85 for "batch mode" processing, 
unattended off-hour communications and other operator-free work. 


BATCH is invoked by inputting the utility file name BATCH (followed by a slash and 
unit number if the disk bearing BATCH is not on unit 0), followed by a space, followed 
by the name of the input file BATCH is to use (followed by a slash and unit number 
if the input file is not on unit 0), optionally followed by a space and an output file 
name (followed by a slash and unit number if the output file is not on unit 0). 


BATCH replaces the keyboard with the contents of the input file. As keyboard input 
is required by running programs, BATCH reads the input file and puts the data in the 
system's keyboard buffer. 


If an output file is specified, all video display output from running programs will be 
recorded in the output file for later review. If the output file specified does not 
exist, BATCH allocates a 20 block file of the specified name on the specified disk. 
Insufficient space on that disk causes a BATCH OUTPUT FILE OPEN ERROR. 


Because of incompatabilities between video and disk file representations, some data 
will not be recorded exactly as it appears on the video display. The most notable 
exceptions involve cursor positioning, reverse video, highlighted video, graphics, and 
carriage control functions. 


Both input and output files are variable record length, ASCII encoded files, like those 
output by the EDIT utility. When the input file is exhausted, BATCH will halt any 
continuing program activity and return the system to the command level (: prompt). 
When the output file is full, BATCH ceases file output but continues to display output 
on the video. 


CAUTION: Batch utility works independent of the standard file system. DO NOT 
CHANGE the files in any way while BATCH is running. This could cause destruction 
of data, do not delete the Batch output file within the Batch procedure or the disk 
directory and data areas could become unaccessable. 


BATCH uses approximately 2000 bytes (8 pages) of user memory. Upon completion, 
BATCH returns this storage to the user. 


Examples: 
:BATCH CONTROLI1 OUT1211 


:BATCH COMU.CTL/1 
:BATCH/1 CTL912 OUTPUT912/1 
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A BATCH input file, written using the EDIT utility, could look like this: 


COMPILE IA1.BAS/1 O=IANALYSE L=IA1.LST/1 LIB=BASIC.LIB 
COMPILE IA2.BAS/1 O=IANALYSE2 L=IA2.LST/1 LIB=BASIC.LIB 
COMPILE IA3.BAS/1 O=IANALYSE3 L=IA3.LST/1 LIB=BASIC.LIB 
COMPILE IMENU.BAS/1 O=IMENU L=IMENU.LST/1 

COMPILE IEND.BAS/1 O=IEND L=IEND.LST/1 

RUN 32 

IMENU 


The Control file above, with the appropriate disks and files in place, would cause a 
set of programs to be compiled and run. If used with an output file, the results of 
the test could be examined the next day, after running the test overnight. Likewise, 
shorter tests could be batched while the operator went to lunch or worked at other 
tasks. 


In the example above, the program invoked by the fourth item on the menu puts a 
message on the video and loops indefinitely. If a program requiring keyboard input 
had been invoked instead, BATCH would terminate when the first input call caused 
the end of the input file to be reached, halting the running program and returning to 
the system command prompt (the : ). 


BATCH Error Messages 
BATCH issues the following error messages: 


NO BATCH INPUT FILE SPECIFIED BATCH was invoked, but no input file 
was specified. 


BATCH INPUT FILE OPEN ERROR The input file specified does not exist, 
eannot be opened, or is not a variable 
record length, ASCII encoded file. 


a 
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BATCH OUTPUT FILE OPEN ERROR The output file specified cannot be 
opened, is not a variable record length 
file, or cannot be allocated because of 
lack of disk space. 


DISK ERROR - BATCH ABORTED An unrecoverable diskette error occurred 
while BATCH was active. 


After an error message is issued, BATCH terminates and returns the system to the 
command level (: prompt). 
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1.8 COPY 
definition: COPY utility 


: COPY [/unit] file specifier [,s][/unit] TO[file specifier [s][/unit]] [1] [0] [L] [u] 


definition: file specifier (COPY) 


filename [/attribute list] [file specifier[,s ] ] 
up to 10 characters including *'s and ?'s[/attribute list] [file specifier [,s]] 


definition: attribute list 


*or Type designator [*or Format designatory - or Write-Protect designator ]] 


The COPY utility copies files from one disk to another, optionally changing names and 
file attributes. 


The COPY utility in its simplest form consists of the command word COPY immediately 
following the system prompt : , followed by a space, followed by one or more file 
specifier's separated by commas, followed by a space, followed by the command word 
TO, followed by a space, followed by a / followed immediately by a number designating 
the disk unit to which the files specified are to be copied. 


NOTE: The COPY utility will not recognize $DIRECTORY or $SYSTEM as valid 
destination file names. 


An optional /unit number immediately following the command word COPY designates 
the disk unit containing the COPY program. An optional /unit number immediately 
following the last file specifier between COPY and TO designates the disk containing 
the files to be copied; a /unit number after a space after the TO, or immediately 
after the last file specifier following the TO, designates the disk unit to which the 
files are to be copied. Default for all disk numbers is disk unit 0. — 


If the optional file specifier list following the command word TO is used, the number 
of file specifiers must match exactly the number of file specifiers preceding the TO. 


An optional I (for INITIALIZE) or O (for OVERWRITE) or L (LABEL copy) or U 
(UPDATE) may follow a space after the last character on the line. 
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If the optional I (initialize) is used, the file directory of the target disk will be cleared 
before files are copied. The I option will not work with any of the fixed disk options, 
only diskettes can be initialized. If the I option is used, the files to be copied must 
be on a different disk than the target disk. If the optional O (overwrite) is used, 
files of the same name as a file being copied will be deleted from the target disk 
before copies are made. 


The L (label) option will also copy the disk label from the source to the destination 
diskette. The U (update) option will only overwrite existing files and will not create 
any new files on the destination diskette. 


The I and L options require the source and destination units to be different. The I, 
O and U options are mutially exclusive. 


COPY uses a "best fit" space allocation method on the target disk. A file will always 
be copied into the free disk space closest to its own size, at the lowest disk address 
possible. If the Initialization option is used, a compressed disk will result, not a sector 
by sector copy of the original. 


Files will be copied in the order specified; if more than one file is designated by a 
file specifier, they will be copied in the order they appear in the original directory. 
If the Overwrite option is not used and a file to be copied matches a filename on the 
target disk, a copy will not be made and a NOT COPIED message will be displayed 


(see Figure 1-3). | 


A FILE SPECIFIER under COPY is either a file name or a group of "wild cards" and 
printable characters, optionally followed by a / followed by an attribute list (see below). 
Two wild cards are available: a * matches any string of characters, of any length 
(including the null string); a ? matches exactly one character (not including nulls, but 
including blanks if they are surrounded by other printable characters). If several file 
specifiers are used, they are separated by commas. 


An ATTRIBUTE LIST consists of one to three characters immediately following a / 
immediately following a file specifier. The first position designates the type of file 
(the T column in the FILES directory display), the second designates the file's record 
format (the F column) and the third the file's write-protect status (the P column). 


If the optional attribute list is not used, the file's attributes will be copied unchanged. 
If the attribute list is used, a * may be used to skip a position; trailing *'s and trailing 
blanks are equivalent. A - in the third position causes the file's write-protect status 
to be set to a blank (not write-protected). 
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The "wild card" file designators can be combined with the attribute designators to 
specify files to be copied by type or format or write-protect status. For instance, if 
all of the object code files on disk unit 0 were to be copied to disk unit 1, the 
command line would look like this: 


: COPY */O TO /1 
or, an alternative form: 
: COPY */0/0 TO /1i 


which explicitly designates disk unit 0. Likewise, if the data files from disk unit 1 
were to be copied to unit 0, the command line would look like this: 


: COPY */D/1 TO /0 


To copy all the write-protected files from unit 0 to unit 1, this command could be 
used: 


: COPY */*P TO /1 

If the write-protect status should be removed, this command would accomplish that: 
s COPY */**P/0 TO */**-+/1 

The - in the third attribute position blanks the write-protect column. 


To copy a diskette which does not contain the COPY program (as, when making a 
backup copy of a data diskette), one of two cases apply. If the COPY program happens 
to appear on the target diskette, COPY can be invoked from there, even if the target 
diskette is to be initialized when the copy is made. 


If neither master nor target diskette bear COPY, then the COPY program must be 
loaded into memory from a diskette that does bear it, the system diskette must be 
removed and the data diskette inserted and a go command given. Assuming the system 
diskette is in unit 0 and the target diskette is in unit 1, the following would make an 
initialized copy: 


: L COPY 
(system disk removed, data disk inserted) 
: G /0 TO /1 I 


Caution: Manually interrupting COPY before normal termination (COPY COMPLETE 
message) except through the abort procedure (see below) may result in destruction of 
data on the target disk. For instance, removing the diskette from the target disk 
unit before COPY COMPLETE could result in a directory error. 


Abort Procedure: CODE ESC (holding down the code key and pressing the escape key) 
terminates COPY safely before COPY COMPLETE. 
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Figure 1-2, COPY Use 


: COPY A* TO /1 

AZ.D/@ COPIED TO A2.D/1 

A1.E/® COPIED TO Al1.B/1 

AZ.D/@ COPIED TO A3.D/1 

APPLE/® COPIED TO APPLE/1 

APUTE/@ COPIED TO APUTE/1 
ALLO-PUTE/® COPIED TO ALLO-PUTE/1 
ALLO-PUTE-/@ COPIED TO ALLO-PUTE~/1 
ALOTEST/@ COPIED TO ALOTEST/1 
ALLO.S/@ COPIED TO ALLO.S/1 

COPY COMPLETED 


: COPY Ax TO B#/1 

AZ2.D/@ COPIED TO B2.D/1 

A1.B/® COPIED TO B1.B/1 

A43.D/® COPIED TO B3.D/1 

APPLE/@® COPIED TO EBPPLE/1 

APUTE/@ COPIED TO BPUTE/1 
ALLO-PUTE/® COPIED TO BLLO-PUTE/1 
ALLO-PUTE-/® COPIED TO BLLO-PUTE-/1 
ALOTEST/@® COPIED TO BLOTEST/1 
ALLO.S/@ COPIED TO BLLO.S/1 

COPY COMPLETED 


= COPY AA# TO BR#/1 
AALO-PUTE/® COPIED TO BELO-PUTE/1 
COPY COMPLETED 


: COPY AP# TO BB#/1 
APPLE/@ COPIED TO BEPLE/1 
APUTE/® COPIED TO BBUTE/1 
COPY COMPLETED 


: COPY A#,B* TO AA#, BE#/1 
AALO-PUTE/@ COPIED TO AAALO-PUTE/1 
APPLE/® COPIED TO AAPPLE/1 

APUTE/@ COPIED TO AAPUTE/1 
EDGMNT/® COPIED TO BBDGMNT/1 

COPY COMPLETED 


Five COPY command uses are illustrated: 


1) 


all files with names beginning with an A are copied from unit 0 to unit 1 with 
unchanged filenames and attributes 

all files with names beginning with an A are copied from unit 0 to unit 1 with a 
B replacing the initial A in the filename 

all files with names beginning with AP are copied from unit 0 to unit 1, the AP 
replaced with BB in the filename 

all files on unit 1 with names beginning AA are copied to unit 0, BB replacing 
the AA in the filename 

all files with names beginning with A or B on unit 0 are copied to unit 1, AA 
replacing A, BB replacing B 
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1) 


2) 


1) 


2) 


Figure 1-3, COPY With Overwrite Option 


: COPY COPY TO /1 

COPY/@ NOT COPIED —- COPY/1 ALREADY EXISTS 
COPY COMPLETED 

: COPY COPY TO /1 0 

COPY/1 DELETED 

COPY/®@ COPIED TO COPY/1 

COPY COMPLETED 


An attempt to COPY the COPY utility from the diskette on disk unit 0 to the 
diskette on unit 1 fails because a copy of COPY already exists on unit 1. 


The second COPY invocation uses the O (overwrite) option (final character O 
in the command line). The file on unit 1 is deleted and the file from unit 0 
is copied onto the disk on unit 1 (if the two files are the same size and no 
open space of equal size on the target directory appears prior to the disk 1 
file, the new copy will be put in the same place as the deleted copy). 
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Figure 1-4, COPY With Attribute Changes 


PILE BOE EOE NBR EOD T F LEN P DATE 
BE2.D 100 101 2 101 166 E V 400 
BB1.B 237 238 2 238 166 E V 000 
BE3.D Fae be] 240 2 240 166 E V 000 


1) * COPY BRe TO CC#/C/1 
BR2.D/® COPIED TO CC2.D/1 
BE1.6/@ COPIED TO CC1.B/1 
BE3.D/@ COPIED TO CC3.D/1 
COPY COMPLETED 


2) : COPY BB* TO DD#/#D/1 
BE2.D/@ COPIED TO DD2.D/1 
BB1.6/® COPIED TO DD1.B/1 
BE3.D/@ COPIED TO DDS3.D/1 
COPY COMPLETED 


3) * COPY BEX TO EE#/##E/1 
BE2.D/@ COPIED TO EE2.D/1 
BB1.B/@ COPIED TO EE1.B/1 
BB3.D/@ COPIED TO EE3.D/1 
COPY COMPLETED 


FILE BOE EOE NBR EOD T F LEN P DATE 
| 
Cc2.D 262 263 2 263 166 C V 000 
CC1.B 264 265 2 265 166 C V 00@ 
CC3.D 278 279 2 279 166 C V 000 
DD2.D 280 281 2 281 166 E D 000 
DD1.B 282 283 2 283 166 E D 900 
DD3.D 284 285 2 285 166 E D 000 
EEZ2.D 286 287 2 287 166 E V @@@E 
EE1.B 288 289 2 289 166 E V OOO E 
EES3.D 290 291 2 291 166 EV @OOE 


First the files on the diskette on disk unit 0 with names beginning BB are listed; all 

have AAA attributes. 

1) They are renamed, CC replacing BB, and C replacing the type (T column) 
designation, and then copied onto the diskette on disk unit 1. 

2) They are renamed with DD replacing the BB and a D is placed in the format 
(F column) designation. 

3) They are renamed with an EE replacing the BB and an E placed in the 
write-protect (P column) designation. 

Finally, the new copies on disk unit 1 are displayed. (Note: The intitial and end 

listings are not from COPY; they were made using the FILES utility.) 


‘-) 


to disk unit 0. 


Figure 1-5, COPY Using Attribute Specifiers 


: COPY #/P/1 TO /® 
PUBSYS.SRC/1 NOT COPIED —- PUBSYS.SRC/® ALREADY EXISTS 


PATCH.BAS/1 NOT COPIED - PATCH.BAS/@ ALREADY EXISTS 
X3.3.2/1 COPIED TO X3.3.2/9 
LDMP.X/1 COPIED TO LDMP.X/® 

CAT.S/1 COPIED TO CAT.S/® 
P.INT.EX/1 COPIED TO P.INT.EX/@ 
INT.TEST/1 COPIED TO INT.TEST/® 
LITNUM.TST/1 COPIED TO LITNUM.TST/®@ 
RAN.TEST/1 COPIED TO RAN.TEST/® 
IPUS.TST/1 COPIED TO IPUS.TST/® 
IMAGE.TST/1 COPIED TO IMAGE.TST/® 
CHR.TST/1 COPIED TO CHR.TST/® 
PRINT.EX/1 COPIED TO PRINT.EX/®@ 
cil COMPLETED 


COPY 


All of the type P (STAR BASIC) source program files on disk unit 1 are ordered copied 
Two of the files are not copied because duplicate filenames already 
exist on disk unit 0. The other source programs are copied onto unit 0. 
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Figure 1-6, COPY With Rename On Same Diskette 


: COPY BR# TO EE# 

BBPUTE/® COPIED TO EEPUTE/® 
BBLO-PUTE/@® COPIED TO EELO-PUTE/® 
BBALO-PUTE/@ COPIED TO EEALO-PUTE/® 
BBPPLE/® COPIED TO EEPPLE/®@ 

COPY COMPLETED 


Four files (all names beginning with BB) are reproduced on disk unit 0 with a name 
change (the initial BB in each case is replaced with an EE). After copy completion, 
the BB files remain on the disk and duplicates with the EE prefix replacing the BB 


in the filename are also present on the disk. 
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Figure 1-7, COPY With Initialization Option 


: COPY/1 * TO /1 I 

SYSD13/@ COPIED TO SYSD13/1 
STARTU.SYS/® COPIED TO STARTU.SYS/1 
FORMAT/@ COPIED TO FORMAT/1 
DSCAN/® COPIED TO DSCAN/1 
COPYD/® COPIED TO COPYD/1 
BDUMP/@® COPIED TO BDUMP/1 
FDUMP/® COPIED TO FDUMP/1 
FPRINT/@ COPIED TO FPRINT/1 
EDIT/® COPIED TO EDIT/1 
BB2.D/® COPIED TO BB2.D/1 
FILES/@ COPIED TO FILES/1 


COPY/® COPIED TO COPY/1 

LGO/@® COPIED TO LGO/1 

DBASIC.OVO/@ COPIED TO DBASIC.OVO/1 
DBASIC.0V1/® COPIED TO DBASIC.OV1/1 
DBASIC.OV2/@ COPIED TO DBASIC.OV2/1 
DBASIC/® COPIED TO DBASIC/1 
PATCH.BAS/® COPIED TO PATCH.BAS/1 
BE1.E/@ COPIED TO BB1.B/1 

BE3.D/® COPIED TO BB3.D/1 

APUTE/® COPIED TO APUTE/1 
ALLO-PUTE-/@ COPIED TO ALLO-PUTE-/1 
ALLO-PUTE/® COPIED TO ALLO-PUTE/1 
APPLE/® COPIED TO APPLE/1 

EE2.D/® COPIED TO EE2.D/1 

FE1.6/@ COPIED TO EE1.B/1 

EE3.D/@ COPIED TO EES.D/1 

COPY COMPLETED 
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The COPY program is loaded from disk unit 1, then the directory of unit 1 is cleared 
and the active files on disk unit 0 are copied onto the unit 1 diskette with no name 


or attribute changes. 


NOTE: Fixed disk drives cannot be initialized. 
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Figure 1-8, COPY Error Messages 


:COPY 

COMMAND FORMAT ERROR 

=: COPY A TO B 

A/0 NOT FOUND 

COPY COMPLETED 

: COPY AE TOC D 

COMMAND FORMAT ERROR 

: COPYAETOCD 

FILE NOT FOUND 

: COPY A,BTOC;D 

COMMAND FORMAT ERROR 

: COPY B#,A# TO /1 

APLDS.S/@ COPIED TO APLDS.S/1 
APPLE/® COPIED TO APPLE/1 
APUTE/@ COPIED TO APUTE/1 
BDGMNT/@® NOT COPIED -— NO DISK SPACE 
COPY COMPLETED 


Six error conditions are shown: 


1) COPY with no parameters results in the COMMAND FORMAT ERROR message, 
indicating a fault in the syntax of the COPY invocation. 

2) If a file specified (filename A, in this case) is not on the disk, or the name appears 
incorrectly in the invocation, the message "A/0 NOT FOUND" appears. 

3) If file specifiers are not separated by commas, the format error message appears. 

4) If the command word COPY is not separated from the rest of the invocation, the 
system looks for a file of that name (in this case, filename COPYABTOCD). 

5) If file specifiers are not separated from the command word TO by spaces, the 
COMMAND FORMAT ERROR message appears. 

6) Ifa file is too large for the available space left on the target disk, the NO DISK 
SPACE message appears. If several files are being copied, and a later file is 
small enough to fit on the disk, it will be copied. In other words, the out of 
space message applies only to the file it appears next to; a new message will 
appear for each file which is too large to be copied. 
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1.9 FILES 


definition: FILES utility invocation 


: FILES[/unit_number] [unit number] [ file specifier [,s ] ] 


definition: file specifier (FILES) 


filename[,file specifier[,s ] ] 
[wild cards[s] ][characters [s] ][ wild _card[s] ][/attribute list][,file specifier [,s ] ] 


definition: wild cards 


definition: attribute list 


* or Type designator(* or Format designator[- or write-Protect designator ] ] 


The FILES utility is used to read and to display diskette directories, to date, rename 
or delete individual files and groups of files, to change file attributes and display 
diskette space utilization. 


The FILES invocation in its simplest form consists of the word FILES immediately 
following the system prompt: . An optional /unit number immediately following the 
word FILES (no intervening spaces) may be used to designate the diskette unit containing 
the FILES program. An optional unit number following a space after the word FILES 
(or /unit number, if used) may be used to designate the diskette unit file directory to 
be read. Both unit numbers default to diskette unit 0 if omitted. One or more file 
specifiers following a spaee may be used after the word FILES (or the unit number(s), 


if used) to designate which directory entries are to be displayed. 
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A file specifier can be a filename or a group of "wild cards" and printable characters. 
Two "wild cards" are available: a * matches any string of characters, of any length 
(including the null string); a ? matches exactly one character (not including nulls, but 
ineluding spaces if they are-surrounded by other printable characters). If several file 
specifiers are used, they are separated by commas. 


File attributes can be included with the "wild cards" to list all files with a specified 
attribute (Type, Format or write-Protect status). The attribute specifier is listed after 
a slash / after the file specifier. Thus, FILES */P would list all STAR BASIC program 
files. 


Examples: Comments: 
FILES program, files from drive 0 
FILES/1 program from 1, files from 0 
FILES 1 program from 0, files from 1 
FILES/2 3 program from 2, files from 3 
FILES PROGNAME displays PROGNAME file only, from unit 0 
FILES/2 PROGNAME,DART.B program from 2, 2 files from unit 0 
FILES I ** displays all files with . in name from unit 1 
FILES/1 3 AR???,*.SRC see Note 1 
FILES B?P*,*.??*,*B see Note 2 
FILES */O,*/**P displays all object files and all write-protected 


files on unit 0 


Note 1: AR??? calls for the display of the file directory entries for all files whose 
names are five characters long, beginning with AR; *.SRC calls for the display of the 
file directory entries of all files whose names end with .SRC . 


Note 2: B?P* calls for the display of file directory entries for files whose names 
begin with a B and have a P as the third character (i.e., BIPPY,BOP,BDP374,B.P, and 
so on); *.??* calls for all files whose names contain a . followed by at least two 
printable characters (i.e. DOG.APB, ARNOLD.RO,A.MEST.O, and so on); *B calls for 
all files whose names end in B. 


After invocation, FILES displays the entries for specified files (or all files if no 
specifiers are used, or no files if the specifier(s) yield no files) in the directory of 
the designated disk. If more files are to be displayed than can be shown on the video 
screen (large font) at one time, the listing is divided into pages (see Figure 1-9). 


The first page displays two header lines at the very top of the screen, followed by a 
file listing, followed by the prompt "HIT SPACE TO CONTINUE". If the space bar 
is used, the next page in the listing will scroll onto the screen. If any character 
except the space bar is: used, the listing display will not continue, but the FILES 
command prompt "ENTER: LIST,UNIT,DELETE,RENAME,ATTRIBUTE,SPACE, DATE, 
EXIT" will appear instead. 


Since there are only two pages in the example display (all 17 files on the diskette are 
listed), and the second page does not fill the screen, part of the first page (including 
the "HIT SPACE..." prompt) remains on the screen. After the listing is complete, the 
FILES command prompt "ENTER..." automatically appears. 
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Figure 1-9, FILES Utility Initial Screen Display 
First Screen Display 

FILES ON VOL DISC.NAME OWNER.NAME CREATED: DATEXX 

FILE BOE EOE NER EOD T F LEN P DATE 
DIRECTORY 12) 1S 16 16 @@@ SF 064 DATE.XX — 
SYSD13 16 44 al 46 078 LV 000 041879 
STARTU.SYS 47 48 2 48 276 S V 000 . 
FORMAT 49 54 6 54 105 S V 000 
DSCAN 55 58 4 58 098 S V 000 
COPYD 59 62 4 62 221 S V 000 
BDUMP 63 57 5 67 259 S V 000 
FDUMP 68 72 5 72 335 S§ V 000 
FPRINT 73 76 4 76 506 S V 000 
EDIT 77 99 23 99 427 SV 000 
HIT SPACE TO CONTINUE 

ww Second Page of Screen Display 

E:DUMP 63 67 > 67 259 SV 000 
FDUMP 68 72 5 = 335 S V 000 
FPRINT 73 76 4 76 506 SV 000 
EDIT 77 a7 23 99 427 SV 000 
HIT SPACE TO CONTINUE 
FILES 103 122 20 122 164 S V 000 
COPY 123 140 18 140 @20 S V 000 
LGO 141 168 28 168 459 S V 000 
DBASIC.0V@ 1469 172 4 172 256 S V 000 
DEASIC.OV1 173 188 16 188 369 SV 000 
DBASIC.OV2 189 210 22 210 295 S$ V 000 
DBASIC 211 232 22 232 286 S V 000 
PATCH. BAS 233 236 4 236 503 PV 000 


ENTER: LIST-UNIT,DELETE ,RENAME -ATTRIBUTE ,SPACE ,DATE EXIT 


1.9 FILES SYSTEM 


The file listing header at the top of the first page in Figure 1-9 shows the disk label, 
owner's name and date the disk was created. These headings, as well as the date 
appearing on the $DIRECTORY line, are set when the disk is FORMAT'ed. If the 
owner's name was John Jones and he called the disk OPERATIONS and he formatted 
the disk on January 1, 1979, the header would look like the following: 


FILES ON VOL OPERATIONS JOHN JONES CREATED 010179 


Disk labels can be up to 10 characters long; owner names can be up to 20 characters 
long; the date can be must be six characters long. 


The second line of headings labels the display which lies below, as follows: 


FILE Filename 

BOE Beginning Of Extent: specifies location of the first block of space 
allocated to the file; up to five digits (decimal) 

EOE End Of Extent: specifies location of the last block of space allocated 
to the file; up to five digits (decimal) 

NBR Number of blocks in file 

EOD End Of Data: specifies block and byte available for data (immediately 


following the last data entry in the file) in form NNNNNBBB where 
NNNNN=block number BBB=byte number 


T Type of file: (first Attribute) specifies type of file, automatically as 
follows: 
L System bootstrap 
s System program (executable at system command level) 
O Object program (compiled STAR BASIC program) 
P Source program (file resulting from successful EDIT) 
D Data file (non-ISAM) resulting from STAR BASIC program 
action 
I ISAM index file 


M ISAM data file 


F Format: (the second Attribute) record format, designated as follows: 
F Fixed length records 
Vv Variable length records 


I ISAM index files 
LEN LENgth of record: decimal integer specifying length of record (0 if not 
a fixed record length file) 
P Protect: (the third Attribute) P if write-protected 
DATE DATE of file; must be six characters; dates can be set by STAR BASIC 


program or by FILES 
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The three Attributes, Type, Format and Protect, can be changed using the FILES 
command ATTRIBUTE; the DATE can be changed by using the FILES command DATE; 
see below. 

1.9.1 FILES COMMANDS 


At the bottom of the second page of the screen display shown in Figure 1-9 is the 
FILES command prompt 


ENTER: LIST,UNIT,DELETE,RENAME,ATTRIBUTE,SPACE,DATE,EXIT 


which lists the eight commands to which FILES will then respond. These commands 
may only be entered after the command prompt line. 


definition: LIST command 


L_ [file specifier] [,file specifier[s,]] [P] 


The LIST command in its simplest form consists of the letter L. One or more file 
specifiers, separated by commas, may be used to limit the files displayed. An optional 
final character P (separated by a space) may be used to output the listing to the 
printer as well as the video display. 


The LIST command calls for the display of file entries on the directory being read. 
If one or more file specifiers are used, the listing will be limited to the files specified; 
default is listing all files. The final optional P causes the file listing to be printed 
in addition to being displayed on the video display unit. 
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Figure 1-10, LIST Command Use 
ENTER: LIST,UNIT,DELETE ,RENAME ,-ATTRIBUTE SPACE ,DATE -EXIT 


LP 

FILES ON VOL DISC.NAME OWNER.NAME CREATED: DATEXX 
FILE BOE EOE NBR EOD T F LEN P DATE 

#DIRECTORY ® 15 16 16 000 S F 064 DATEXX 

SYSD13 16 4S 31 46 078 LV 000 041879 

STARTU.SYS 47 48 2 48 276 S V 000 

FORMAT 49 54 6 54 105 S$ V 000 

DSCAN 55 58 4 58 098 S V 000 

COPYD 59 62 4 62 221 S V 000 

EDUMP 63 67 > 67 259 SV 000 

FDUMP 68 72 =) 72 335 S V 000 

FPRINT 73 76 4 76 506 S V 000 

EDIT 77 99 23 99 427 S V 000 

FILES 103 122 20 122 164 S V 000 

COPY 123 140 18 140 020 SS V 000 

LGO 141 1468 28 168 459 S$ V 000 

DBASIC.OV® 149 172 4 172 256 S V 000 

DBASIC.OV1 173 188 16 188 369 S V 000 

DBASIC.0V2 189 219 22 2190 295 S V 000 

DBASIC 211 22 22 232 286 S V 000 

PATCH.BAS 233 236 4 236 503 PV 000 

ENTER: LIST,UNIT,DELETE -RENAME ,ATTRIBUTE ,SPACE ,DATE,EXIT 

L *#.# 

FILES ON VOL DISC.NAME OWNER.NAME CREATED: DATEXX 
FILE BOE EOE NBR EOD T F LEN P DATE 

STARTU.SYS 47 48 2 48 276 S V 000 

DBASIC.OV® 149 17Z 4 172 256 S V 000 

DEASIC.OV1 173 188 16 188 369 S V 000 

DBASIC.O0V2 189 210 22 210 295 S$ V 000 

PATCH.BAS 233 236 4 236 503 PV 000 

ENTER? LIST,/UNIT,DELETE »-RENAME ,ATTRIBUTE », SPACE ,DATE »EXIT 

L #DE+* 

FILES ON VOL DISC.NAME OWNER.NAME CREATED: DATEXX 
FILE BOE EOE NER EOD T F LEN P DATE 

DBASIC.O0V® 169 17Z 4 172 256 S V 000 

DBASIC.OV1 173 188 16 188 369 S V 90@ 

DBASIC.OV2 189 210 22 210 295 § V 000 

DBASIC 211 2aZ 22 232 286 S V 000 

ENTER: LIST,UNIT,DELETE ,-RENAME ,ATTRIBUTE ,SPACE ,DATE -EXIT 

Lo #. PP? 


(continued) 
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Figure 1-11, LIST Command (Cont'd) 


FILES ON VOL DISC.NAME OWNER NAME CREATED: DATEXX 

FILE BOE EOE NER EOD T F LEN P DATE 
STARTU.SYS 49 50 2 5®@ 271 S V 000 013080 
DBASIC.OV® Pe Fetes 4 255 256 S V 000 013080 
DBASIC.OV1 256 271 16 271 369 S V 909 013080 
DEBASIC.OV2 ee 293 an 293 295 S$ V 000 913980. 


ENTER: LIST,UNIT,DELETE »,RENAME ,-ATTRIBUTE, SPACE ,DATE -EXIT 


L P?PSt © 

FILES ON VOL DISC.NAME OWNER NAME CREATED: DATEXX 
PALE BOE EOE NER EOD 1 F LEN P DATE 

SYSD13 16 48 33 48 054 -L V 000 013080 

FLS 37 63 7 63 503 S V 000 012080 


ENTER! LIST,/UNIT,DELETE ,RENAME ,-ATTRIBUTE ,SPACE ,DATE ,EXIT 
L DBASIC 


FILES ON VOL DISC.NAME OWNER NAME CREATED: DATEXX 
FILE BOE EOE NEBR EOD T F LEN P DATE 
DEASIC 294 315 22 315 286 S V 000 013080 


ENTER? LIST,-UNIT,DELETE »RENAME -ATTRIBUTE,SPACE ,DATE -EXIT 


In each case, the command is given after the command prompt, followed by the display. 
The L P command lists all files on the printer, as shown. The other commands shown 
output on the video display, in each case clearing the screen before the display is 
shown. 
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Examples: 
L 
LIST 
LAUDABLE 
L ARMENU 
L AR* 
i; BY F* PTT? 


L *T*,*O 


b 29.72 fer 


L */P,*/*V,*/**#P 
L B*/O P 


L P 
Ly? FP 


SYSTEM 


Comments: 


lists all files 

lists all files 

lists all files 

lists only file ARMENU entry 
lists all files beginning AR 


lists all files beginning with R and 
F and all files whose names are 
four letters long, beginning with 


P 


lists all files with a T in name, 
and all files ending in O 


Lists all six character name files 
with . in fourth position and all 
files ending with a . followed by 
three characters 


lists all type P, format V and 
write-protected files 


lists all files beginning with B of 
type O on printer 


lists all files on printer 


lists all files with . in name on 
printer 


Filenames containing a space, a comma, a * or a ? require use of a ? or * to replace 
the space or comma or ? or * in all FILES command use. While use of these characters 


in filenames is legal, it is inconvenient. 


Example: 
Filename: YOU ARE 


File specifier: YOU?ARE or YOU*ARE 


YOU?ARE also matches YOU-ARE YOU.ARE and so on. 
YOU*ARE in addition matches YOUBENARE and so on. 


Definition: UNIT command _ 


U unit number 


The UNIT command consists of the letter U followed by a space, followed by a unit 


number designating the diskette unit to be read. 


The UNIT command changes the file directory being read and displayed. 
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Figure 1-12, UNIT COMMAND 


ENTER: LIST;UNIT DELETE -RENAME ,ATTRIBUTE ,SPACE ,DATE -EXIT 
Ul 

UNIT 1 

ENTER: LIST,/UNIT,DELETE ,RENAME ,-ATTRIBUTE »SPACE ,DATE -EXIT 


The command U 1 causes FILES to switch to diskette unit 1, following which the 
confirmation UNIT 1 is displayed, followed by the command prompt ENTER.... 


definition: DELETE command 


D file specifier [,file specifier [,s ]][V] 


The DELETE command consists of the letter D followed by a space, followed by at 
least one file specifier. If more than one file specifier is used they are separated by 
commas. An optional character V may be used at the end of the specifier list. 


The DELETE command deletes entries from the disk directory. All files specified will 
be deleted. If the optional final V (Verify) is used, the file names will be listed 
successively on the video display, each followed by a question mark. If the user 
answers with a Y, that file will be deleted; any other response will leave the file 
entry in the directory. : 


Whether the optional V (Verify) is used or not, after all deletion messages have been 
issued, a final prompt 


OK? 
is issued, requiring a Y response for the deletion(s) listed above to be implemented; 


any other response (including a carriage return with no other input) causes the deletions 
to be cancelled and the files to be maintained in the directory. See Figure 1-13. 


Examples: Comments: 
p-* deletes all files 
DELETE * deletes all files 
DELIVER * deletes all files 
D ARMENU deletes ARMENU only 
D *.SRC - deletes all files ending in .SRC 
D APPLE,*.???,?E* deletes file APPLE, all files whose 


names end in . followed by exactly 
three characters and all files 
whose second letter is E 


D */O deletes all type O (object code) 
files 
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D */*F V deletes all format F (fixed record) files, subject 
to operator verification on each file. 

D* V . deletes all files, subject to operator verification 
on each file. 

D *BAS* V deletes all files containing BAS, subject to 


operator verification on each file. 


Figure 1-13, DELETE COMMAND WITH VERIFY 


ENTER: LIST,UNIT,DELETE ,RENAME ,ATTRIBUTE »SPACE ,DATE EXIT 
D# V 

DELETE ISETY 

DELETE ILSET? 

DELETE IRSET? 

DELETE ISET.SRC? 

DELETE IRSET.SRC? 

DELETE NAME’? 

DELETE ALOTEST? 

DELETE ALLO.S? 

DELETE ALLO? 

DELETE APPLE? Y 

APPLE #DELETED+ 

OK? Y 

ENTER! LIST,UNIT,DELETE ,RENAME ,ATTRIBUTE ,SPACE ,DATE ,EXIT 


The command D * V causes FILES to display the DELETE filename? prompt for all 
files of the directory. A Y response (as in APPLE above) causes the file to be deleted; 
any other response (including carriage return with no other input, as above) leaves the 
file in place. A Y response after the final OK? is required for the deletions to be 
implemented. Any other response (including a carriage return with no other input) 
cancels all deletions and leaves all files in place. If no file is given a Y in the 
verification list, no OK? prompt will be issued and no files will be deleted. 


definition: RENAME command 


R_ file specifier file specifier [ ,file specifier file specifier... ]] 


The RENAME command in its simplest form consists of the letter R followed by a 
file specifier designating the present filename(s), then a blank, followed by a file 
specifier designating 
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the new name(s). More than one pair of file specifiers can be used to designate 
additional files to be renamed. The pairs of filenames in the command line are 
separated by commas. ; 

The RENAME command changes file names. 


Figure 1-14, RENAME Command Use 


FILES ON VOL DISC.NAME OWNER.NAME CREATED: DATEXX 
FILE BOE EOE NEBR EOD T F LEN P DATE 
ALLO-PUTE- 63 67 2 67 259 E V 900 
A-TEST 73 76 4 76 506 S V.000 
ALLO-PUTE 141 168 28 168 459 E V 000 
APUTE 223 236 4 236 503 E V 000 
ENTER: LIST,UNIT,DELETE »RENAME ,-ATTRIBUTE ,SPACE -DATE -EXIT 
R A~TEST APPLE 
A-TEST: APPLE 
OK? Y | 
ENTER: LIST,UNIT,DELETE,RENAME -ATTRIBUTE ,SPACE ,DATE ,EXIT 
L At 
FILES ON VOL DISC.NAME OWNER.NAME CREATED: DATEXX 
FILE BOE EOE NBR EOD T F LEN BP DATE 
ALLO-PUTE- 63 67 = 67 259 E V 000 
APPLE 73 76 4 76 506 S V 000 
ALLO-PUTE 141 168 28 168 459 E V 000 
APUTE 233 236 4 236 503 E V 000 
ENTER? LIST,UNIT,DELETE »-RENAME -ATTRIBUTE ,SPACE ,DATE -EXIT 


First the files with names beginning with the letter A are listed, then the file A-TEST 
is renamed APPLE. After the command is given, FILES responds 
A-TEST: APPLE 
OK? 
A Y following the OK? changes the name; any other response cancels the name change. 
Finally, the names beginning with A are listed again, using the L A* command, to 
show that the change has been made. 
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Examples: Comments: 

R APPLE PEAR renames file APPLE to PEAR 

RENAME PILOT P-LOT_ renames file PILOT to P-LOT 

RANDOMIZE ARG.B PLANS renames ARG.B to PLANS 

R DOG1 DOG,CAT9 CAT renames DOG1 to DOG, CAT9 to CAT 

R D* A* renames all files beginning with D, 
replacing D with A 

R *B * renames all files ending in B, dropping 
the B 

R */O A*/O renames all type O (object code) files, 
adding an A to the beginning of the 

; filename 7 
R */*F *,D/*F renames all format F (fixed record 


length) files, adding a .D to the end of 
the filename 


definition: ATTRIBUTE command 


A file specifier[,s ]* or Type designator[* or Format designator 
A [-_or write-Protect designator 


The ATTRIBUTE command in its simplest form consists of the letter A followed by 
a space, followed by one or more file specifiers separated by commas, followed by a 
space, followed by one, two or three letters. 


A * may be used to skip a position, leaving that attribute unchanged. A - in the 
third (write protect) position changes that position to a blank. At most 3 characters, 
whether alphabetics, *'s or -, may follow the space following the last file specifier. 


The ATTRIBUTE command is used to change one or more of the three file attributes: 
file Type designation, record Format designation and write-Protect status (the T, F 
and P columns in the listing display). While the Type and Format designations are 
set automatically (see the initial discussion of the listing display for these designations) 
and only a P in the write-Protect position will cause the file to be write-protected, 
any characters may be inserted in the three attribute positions using this command. 
Trailing blanks in the attribute designator positions are ignored, so the - must be used 
to blank the write-Protect designation. A * in any of the three positions will cause 
that attribute to remain unchanged. 


Changing the Attribute listing in the diskette directory does not change the character- 
istics of the file itself. Changing Attribute listings to false or illegal codes can have 
undesirable consequences. For instance, changing the Type designator of the system 
program to Type P instead of Type L could cause a failure (NO LOADABLE FILE, 
shown by the LED's) if the diskette is used for a CODE LOAD. The F-85 would look 
for a Type L file, not find it, and issue the error message. Likewise, some of the 
file 1/O operations from STAR BASIC programs require specific Attribute listings in 
the directory. 
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Figure 1-15, ATTRIBUTE Command Use 


FILES ON VOL DISC.NAME OWNER.NAME CREATED: DATEXX 
FILE BOE EOE NBR EOD T F LEN P DATE 

APUTE 100 101 2 101 166 E V 000 

ALLO-PUTE 239 240 2 240 166 E V 900 

APPLE : 241 242 2 242 166 E V 000 

ENTER? LIST,UNIT,DELETE ,RENAME ,-ATTRIBUTE ,SPACE ,DATE -EXIT 

A APPLE RST 

APPLE /RST 

OK? Y 

FILES ON VOL DISC.NAME OWNER.NAME CREATED: DATEXX 
FILE BOE EOE NBR EOD T F LEN P DATE 

APUTE 100 101 2 101 166 E V 000 

ALLO-PUTE 239 240 -2 240 166 E V 000 

APPLE 241 242 2 242 166 RS 600 T 


ENTER: LIST,UNIT,DELETE ,RENAME ,ATTRIBUTE ,SPACE ,DATE -EXIT 


An L A* command (not shown) was used to list the filenames beginning with the letter 
A, then the ATTRIBUTE command was used to change the attributes of the file APPLE 
from P V (blank) to R S T , arbitrarily chosen designators. After the command is 
input, FILES responds 


APPLE/RST 

OK? 
A Y following the OK? causes the attributes listed after the / to be inserted in that 
file's directory listing. Any other response leaves the directory unchanged. Finally, 
another L A* command (not shown) was used to display the changed directory listing. 
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Examples: Comments: oO 
A ORD.B P changes Type designation of file ORD.B 
to P 
A ORD.B *P changes Format designation of ORD.B 
to P 
A ORD.B **P changes write-Protect status of ORD.B 
to P 
ATTRIBUTE A* DFP changes attribute designations of all 
filenames beginning with A to Type D, 
Format F, write-Protect P 
ATTATURK ?D* *V changes Format designation to V for all 
filenames with a D as the second letter 
A SOCSEC **- changes write-Protect status of file 
SOCSEC to blank 
A */DT change all type D (data files) to type 
designation T (presumably a 
programmer-designated type indication) 
A */*F *FP add write-protect character (P) to all 
format F (fixed length record) files 
definition: SPACE command 
S) 
The SPACE command displays the free blocks available on the diskette or fixed disk 
being read, the total number of free blocks, the largest free area and the number of 
filenames in use. 
Figure 1-16, SPACE Display 
ENTER: LIST,UNIT,DELETE,RENAME ,ATTRIBUTE ,SPACE ,DATE ,EXIT 
S 
FREE BLOCKS 
FROM TO NUMBER 
49 58 19 
468 7Z S 
19® 192 3 
169 232 64 
Zor 923 587 
TOTAL FREE BLOCKS: 769 
LARGEST FREE AREA: 687 
11 OUT OF 127 FILE NAMES USED 
ENTER: LIST,UNIT,DELETE,RENAME -ATTRIBUTE -SPACE ,DATE,EXIT 
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definition: DATE command 


DA file specifier[,s] 6 printable characters 


The DATE command in its simplest form consists of the letters DA followed by a 
space, followed by a file specifier, followed by a space, followed by a 6 character 
string to be inserted in the DATE column of the directory listing of the filenames 
specified. More than one file specifier may be used if desired, separated by commas, 
but all files specified will be given the same string. If a blank is desired in the DATE 
column, six blank spaces should be used instead of other characters as the final portion 
of the DATE command line. 


The DATE command appends the date (or other information contained in six characters) 
in the DATE column of the directory filename listing. 


Examples: Comments: 
DA ORD.B 123079 dates file ORD.B Dec. 30, 1979 
DATE B* 011279 dates all filenames beginning with 
B Jan. 12, 1979 
DABBLE * 030179 dates all files March 1, 1979 
DA */O 051579 data all type O (object code) files 
oO May ‘15, 1979 
DA */DF 110480 data ail type D (data) format F 
(fixed length records) November 4, 
1980 
DA *B*, *N*, *.22?2? THESE tags all filenames containing a B 


or an N or ending in a . followed 
by exactly 3 characters with the 
message THESE (with a trailing 
blank) 

DA APPLE,PEAR,ORANGE FRUITS tags filenames APPLE, PEAR and 
ORANGE with the label FRUITS 
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Figure 1-17, DATE Command Use Nad 
PILE BOE EOE NBR EOD T F LEN P DATE 
ALLO-PUTE- 63 67 Fe 67 259 E V 000 
APPLE 73 76 4 76 506 S V 000 
ALLO-PUTE 141 1468 28 168 459 E V 000 
APUTE 233 236 4 236 503 E V 000 


ENTER: LIST,UNIT,DELETE ,RENAME -ATTRIBUTE ,SPACE ,-DATE »-EXIT 
D APPLE DATEXX 

APPLE #DELETED+ 

OK? N 

ENTER: LIST,UNIT,DELETE ,RENAME ,ATTRIBUTE »SPACE ,DATE -EXIT 
DA APPLE DATEXX 

APPLE DATEXX 

OK? Y 

ENTER? LIST,UNIT,DELETE ,-RENAME ,-ATTRIBUTE ,SPACE ,DATE -EXIT 
L At 


FILES ON VOL DISC.NAME OWNER. NAME CREATED: DATEXX 
PILE BOE EOE NBR EOD T F LEN P DATE 
ALLO-PUTE- 63 67 pe 67 259 E V 000 Na 
APPLE 73 76 4 76 506 S V 000 DATEXX 
ALLO-PUTE 141 168 28 168 459 E V 000 
APUTE 233 236 4 236 503 E V 000 


ENTER: LIST-UNIT,DELETE ,-RENAME ,ATTRIBUTE »-SPACE ,-DATE -EXIT 


The L A* command (not shown) was used to display all filenames beginning with A. 
The first attempt to date the file APPLE failed, because the A of the DA command 
word was omitted, making it a Delete command. When a non-Y response was returned 
after the delete prompt, the delete sequence was aborted. The proper date command 
was then given, adding the 6-character string DATEXX to the filename APPLE. After 
the DATE command was given, FILES responded 

APPLE DATEXX 

OK? 
The Y response approved the change and another L A* command (not shown) displayed 
the changed listing. 
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definition: EXIT command 


The EXIT command consists of the letter E. 


The EXIT command ends the operation of FILES and returns the system to system 
command level. 


Figure 1-18, EXIT Command Use 


FILES ON VOL DISC.NAME OWNER.NAME CREATED! DATEXX 
FILE BOE EOE NBR EOD T F LEN P DATE 

ALLO-PUTE- 63 47 bs 67 259 EV 00@ 

APPLE 73 76 4 76 506 SV 000 DATEXX 

ALLO-PUTE 141 168 28 168 459 E V 000 

APUTE 233 236 4 236 503 EV 000 


ENTER: LIST,UNIT,DELETE ,RENAME ,ATTRIBUTE ,SPACE ,DATE EXIT 


Oo : 


An L A* command (not shown) displayed the filenames beginning with A. The EXIT 
command E ends FILES' operation and returns the system to command mode, signified 
by the : prompt. 
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An invalid command is any command word not beginning with L,U,D,R,A,S,DA or E. 
FILES responds with the error message 
INVALID COMMAND 
and gives the command prompt again. 
Figure 1-19, INVALID COMMAND Use 

ENTER: LIST,UNIT,DELETE,RENAME -ATTRIBUTE,SPACE »DATE ,-EXIT 

FD 

INVALID COMMAND 

ENTER: LIST-/UNIT,DELETE, RENAME ATTRIBUTE ,SPACE ,DATE ,EXIT 

W 

INVALID COMMAND ; 

ENTER: LIST,UNIT,DELETE RENAME ATTRIBUTE ,»SPACE ,DATE ,EXIT 

p 

INVALID COMMAND 

ENTER: LIST,UNIT,DELETE,-RENAME ,ATTRIBUTE »SPACE ,DATE -EXIT 

INVALID COMMAND 

ENTER: LIST,/UNIT,DELETE -RENAME -ATTRIBUTE »SPACE »DATE -EXIT 
The invalid commands given were FD, W, P and (blank). In each case, FILES responds 
with the error message and a new command prompt. 
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1.10 BDUMP 


BDUMP displays or prints the hexidecimal and ASCII code of designated blocks of a 
disk. 


definition: BDUMP invocation 


: BDUMP[/unit ] unit_to be read starting block [end block ][L] or [P] 


: system command prompt 

BDUMP utility file name 

/unit disk unit number of disk bearing BDUMP (default is 
unit 0) 

unit to be read disk unit number of disk to be read 

starting block block number of first block to be read 

end block block number of last block to be read (default is to 
continue reading until CODE ESC is pressed) 

L or P Causes output to be Listed on printer (default is video 
display) 

Examples: 


1) : BDUMP 1 320 320 L or P 
2) : BDUMP 0 450 

3) : BDUMP/1 0 0 15 

4) : BDUMP 0 0 L or P 


1) prints block 320 from unit 1 (disk block numbers start at 0). 

2) displays block 450 and following blocks on the video display; successive blocks 
will be displayed until CODE ESC is pressed. 

3) BDUMP is taken from unit 1, blocks 0 through 15 (the directory) on unit 0 are 
displayed successively on the video. 

4) prints blocks 0 and following blocks until CODE ESC is pressed. 


1.11 FORMAT SYSTEM 


1.11 FORMAT 


The FORMAT utility prepares "factory fresh" diskettes for use by the system, writing 
in sector headers and performing a hard error scan of the diskette at the same time. 


definition: FORMAT invocation 


: FORMAT[/unit ] 


FORMAT is invoked by inputting the utility file name FORMAT to the system command 
prompt (the : ). If the FORMAT program file is not on unit 0, the optional slash 
followed by a disk unit number is used to specify the disk unit bearing FORMAT. 
FORMAT is self-prompting, as shown in Figure 1-20. 

If the diskette drive designated for Format is not ready when "G" is entered, the error 
message shown below will be displayed. The system will then return the system prompt 
(:) and the Format program must be restarted. 


DISK IS NOT READY. FORMAT ABORTED 
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Figure 1-20, FORMAT DIALOGUE 


(a) | 
DISK FORMAT PROGRAM FORMATTING TRACK @@ 


DRIVE # ?1 


* DISK IN SELECTED DRIVE WILL BE FORMATTED AS A SINGLE SIDED DISK 
TYPE DISK LABEL NAME (10 CHARACTERS) 


TYPE OWNER NAME (2@ CHARACTERS) 
TYPE THE DATE IN THE FORMAT MMDDYY 


WHEN READY WITH NEW DISK IN DRIVE, TYPE G 
ANY OTHER KEY WILL RESTART PROGRAM 


FORMATTING COMPLETE 


Enter the information requested by the prompts. 


The "FORMATTING TRACK __" field then appears. Three complete 
diskette passes occur (track numbers are alternately incremented from 00 
to 76, then decremented down to 00, and finally incremented back up to 
76). This process includes a test of the diskette media integrity: the 
occurrence of errors indicates the diskette cannot be properly formatted 
as a result of defective media. 


(C) Following successful execution of (B) , the "FORMATTING COMPLETE" 
message is issued. 


*The message will state single or double sided, depending on the system being 
used. 


1.12 DSCAN SYSTEM 


1.12 DSCAN 
DSCAN reads every block on the designated unit to check for hard disk errors. 


definitions _DSCAN invocation 
: DSCAN [/unit] unit 


DSCAN will continue to scan the diskette or fixed disk until CODE ESCape -halts 
scanning. The message "PASS number", displayed on the CRT, signals the beginning 
of each pass across the disk. 


If a disk error is encountered, the message shown below will appear on the CRT and 
it will be printed out as well: 


ERROR Block nnn STATUS XX,YY 


The "nnn" is the Block number where the error was detected. The error status output 
is two bytes separated by a comma. The first byte "XX" are the contents of the 
controller status register. The second byte "YY" represents the error register. The 
DSCAN utility should be run for a minimum of 2 complete passes. This allows for a 
more complete error check. 
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1.13 DX-85M COMMANDS 


The system obeys a variety of commands as well as utility invocations. These commands 
are primarily used by systems programmers in debugging the system itself, but a few 
of the commands are used in applications program development and use, most notably 
the Load and Go commands. 


Table 1-6, DX-85M Commands 


Command name Syntax Function 
LOAD L filename [/unit ] loads program into 
memory 
GO G [parameters ] runs currently loaded 
program from current 
position 
HEX H address value [ value... ] alters value(s) starting 


at memory address 


DUMP D address ending address displays values from 
memory address; 
dumps 2 bytes unless 
ending address is 


specified 
SET S alphabetic value sets specified register 
to value 
BREAKPOINT B [address ] sets a breakpoint 


at address if specified; 
otherwise, clears 
all breakpoints 


All addresses and values are hexidecimal. 
Example: 


: L COPY 
: G/1 TO /OI 


The example would load the COPY utility into memory. The system disk could then 
be removed from unit 0 and a backup disk installed to accept the copy of the disk 
on unit 1. 
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THE STAR BASIC PROGRAMMING LANGUAGE 


2.0 STAR BASIC VOCABULARY 
2.0.1 Language Overview 


STAR BASIC is a business-oriented, English-like high level programming language 
specifically developed for the F-85 desktop computer system. 


With the DX-85M operating system and its utilities, the COMPILE compiler and the 
RUN/RUNB run-time monitor and the STAR BASIC language offers high speed, memory 
efficient operations in the development and implementation of a wide variety of 
applications. 


A wide range of controls, flexibility and a variety of program structures available in 
STAR BASIC simplify applications programming. Features include: 


e Numeric manipulation with 14-digit precision and extensive string-handling 
capability, including single and double-dimensioned arrays and automatic 
string-to-numerie and numeric-to-string conversions 


e Formatted and edited input and output and extensive video and printer 
control functions, including video graphics and fine control of both video 
and printer functions 


* Single and multi-user programming, including on-error chaining and a 
c variety of common value and parameter passage for efficient multi-user 
program segmentation and partition, and including the option of fully 

block-structured programming 


* English-like or numeric line labels of up to 32 characters; English-like 
variable and array and subroutine and function names; both title and 
in-line comment statements, making internal program documentation easy 
for more efficient program maintenance 


e Extensive utility and I/O control functions and nearly unlimited definition 
of user-defined functions to fit any special calculation or I/O requirements 


e Both single line and statement group conditionals, plus ELSE options for 
ON...GOTO's and ON...GOSUB's, plus a full set of logical operators 


6 Both fixed and variable length string arrays, making blank-padding auto- 
matic if desired, plus optional linkage of array and variable memory 
locations, eliminating repeated assignment lines and making string refer- 
ences easy to understand and use 


® Extensive file handling capability, including sequential and random access 
files, Indexed Sequential Access Method files and print-file spooling 


STAR BASIC programs consist of series of statements. Each statement is made of 
an optional statement label (which may be either purely numeric or an alphanumeric 
am) mixture) and an optional statement body. 


Table 2-1, STAR BASIC Statements 


LANGUAGE 


Statement bodies are made of directive reserved words combined with elements and 
expressions. Elements may be constants or variables or arrays or functions; expressions 
may be mathematical, relational or logical; values are numeric or string or truth- 


functional. 


STAR BASIC statements are of eleven types, as shown in Table 2-1. 


Null statements 


blank line 
line label alone 


Comment statements 


REM 
TITLE 
EJECT 
LIST 


Assignment statements 


LET 
BASE 


Declarative statements 


DIM 
DATA 
COPY 
COMMON 
IOLIST 
STOP 
END 


Table 2-1, STAR BASIC Statements 


used for readability 


used as target for transfer statements 


remark; used to document program 
titles pages of compiler listing 
allows form feed between routines 
turns compiler printout on or off 


assigns value of expression to variable 
variables share memory location 


dimension; size arrays, designate FIXED length or BASED 


hold values for internal input/output 


inserts code from routine library file during compilation 


assigns variables to common memory area 
expression list for READ and WRITE statements 


halt program execution 


halt program execution and compilation; ends every routine 


Loop/conditional statements 


FOR-NEXT 
IF-THEN 
IF-THEN-ELSE-EN DIF 
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create iteration loops 


logical test determines consequent statement's execution 


logical test switches between two statement groups 
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Table 2-1, STAR BASIC Statements 


Transfer/subroutine statements 


GOTO 
GOSUB 


EXIT 
CALL CHAIN 


Error handling statements 


ON ERROR 
ERROR 
RESET ERROR 


Internal input/output 


READ 
RESTORE 


unconditional transfer to labeled statement line 

unconditional transfer with possibility of return 

numeric switch among transfer targets 

numeric switch among targets with possibility of return 
transfer to line following last GOSUB 

invoke external subroutine, may pass parameters to subroutine 
heads external subroutine; may accept parameters from call 
function external subroutine; invoked by function's use 

sends control and values back to calling routine 

invokes new program, clears current program from memory 


executes statement on error, supresses system error handling 
invokes specified error 
supresses previous ON ERROR trap 


read values from DATA statement into variables 
reset DATA pointer to labeled DATA statement 


Keyboard/video/printer input/output 


INPUT 
PRINT 
WRITE 


File input/output 


ALLOCATE 
OPEN 
CLOSE 
RENAME 
DATE 


File record input/output 


READ 
WRITE 
DELETE 
UNLOCK 
REWIND 


read value from keyboard into variables 
write on video display (edit, format data; includes graphics) 
write on printer (edit, format data) 


create file, reserve space on disk 

assign logical file number, set access characteristics 
release logical file number, may truncate or delete file 
change file name of open file 

set date in open file's directory listing 


read data from record into variables 
write data from expressions into record 
delete record 


- unlock record locked by READ statement 


reset read pointer of files 
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2.0.2 Syntax Notation 


Each element and statement of STAR BASIC is structurally defined in a formal syntax 
definition in its vocabulary subsection. In addition, these syntax definitions are repeated 
in Appendix A for quick reference. 

Formal syntax definitions are given in this form: 


definition: statement or element name 


syntax definition 


Where several forms are allowable, they may be given as several lines within the 
definition box, in this form: 


definition: statement or element name 


first form defined 
second form defined 


third form defined 


This multiple form is also used to list the various components of a complex element, 
as in the definition of data type from Subsection 2.2: 


definition: data type 


numeric 


string 


Statement definitions may continue over more than one line, just as STAR BASIC 
statements may continue over more than one line. The continuation symbol” is used 
at the left end of each continued line in definitions to show that the line continues. 
In STAR BASIC statements, the continuation symbol must appear at the left margin 
of each line, but in definitions the lines are double-spaced for easier reading. 


LANGUAGE 2.0.2 Syntax Notation 


Square brackets { ] are used to mark expressions which are optional. Except for 
brackets and the continuation symbol, all symbols and UPPER CASE WORDS in syntax 
definitions must appear as shown (with an exception: see note on upper case below). 
Syntactic variables, which are replaced by appropriate elements and expressions in 
functioning statements, are underlined lower case words. 


In functioning STAR BASIC statements, upper and lower case are equivalent outside 
of string literals, so while all UPPER CASE WORDS in syntax definitions must appear 
as shown in the definition, they do not necessarily need to be upper case. 

For example, 


definition: ON GOSUB statement 


ON numeric expression GOSUB statement label list [ELSE statement] 


In this definition, ON, GOSUB and ELSE (if used) must appear as shown, separated by 
the appropriate expressions or lists. numeric expression, statement label list and 
statement are syntactic variables defined elsewhere in the definition list and would be 
replaced by instances of the appropriate type and form in functioning statements, viz.: 


ON Index GOSUB 1,2,3,4,5,6,7 
on J*I+Number$ gosub Here,There,Everywhere 
ON Helpful gosub One,Two,Three Else GOTO Restart 


In the ON Index... example, Index is the numeric expression, 1,2,3,4,5,6,7 is the statement 
label list, and the ELSE option is not used. 

In the on J... example, J*I+Number$ is the numeric expression, 
Here,There,Evervwhere is the statement label list, and the ELSE option is not used. 
In the ON Helpful... example, Helpful is the numeric expression, One,Two,Three is the 
statement label list, and GOTO Restart is the statement. 


ON...GOSUB, on...gosub, ON...gosub...Else are all appropriate. 
Even On...GoSub...eLsE would be equivalent to ON...GOSUB...ELSE. 


In some eases, particularly input/output statements, a general form of the statement 
is defined, followed by specific forms. The ALLOCATE statement definitions are a 
good example: first the general form is defined, then the individual forms as used 
for sequential, random access and ISAM files. The file and record I/O subsections of 
the text are divided this way as well: first the general form of the statement is 
discussed, then the individual forms as used for sequential, random or ISAM files. If 
usage is the same for all types of files, only one discussion will be given ‘as in the 
DATE or RENAME statement subsections). 
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Examples: 


definition: ALLOCATE statement 


ALLOCATE (FILE=string expression,NREC=numeric expression, 
A RECLEN=numerie expression[,LFN=numeric expression ] 


A [,RECFMT=string expression]LORG=string expression ] 
aAL,KEYLEN=numeric expression] }ERL=statement label ] 


a L,UNIT=numerie expression] [IUNIT=numeric expression]) 


definition: _ ALLOCATE statement (sequential files only) 


ALLOCATE (FILE=string expression,RECLEN=numeric expression, 
ANREC=numerie expression [,ERL=statement label ] 


_ a({,UNIT=numerie expression] ) 


definition: | ALLOCATE statement (random access files only) 


ALLOCATE (FILE=string expression,RECLEN=numerie expression, 
ANREC=numeric expression,RECFMT=string expression, 
AORG=string expression[,ERL=statement label ] 


\ LUNIT=numeric expression] ) 


definition: ALLOCATE statement (ISAM files only) 


ALLOCATE (FILE=string_expression,LFN=numeric expression, 
ANREC=numeric expression,RECLEN=numeric expression, 
ARECFMTs=string expression,ORG=string expression, 
aAKEYLEN=numerice expression, ERL=statement label] 


‘ [,UNIT=numeric expression ][,IUNIT=numerie expression]) 
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2.053 Syntax Overview 


The STAR BASIC character. set is used to write all STAR BASIC labels, directives, 
operators and elements outside of string literals (character string constants). The 
STAR BASIC character set consists of the alphanumeric characters and the symbols: 


STAR BASIC character set 


alphanumerics 
alphabetices 


upper case ABCDEFGHIJKLMNOPQRSTUVWXYZ 
lower case abedefghijklmnopqrstuvwxyz 
numerics 0123456789 
period ° 
symbols (blank) "$ & <> =+t-* /\l),.3 8a! 


STAR BASIC programs consist of a series of statements. Each statement consists of 
an optional label and an optional statement body. A label can be purelv numeric, 
optionally followed by a colon, or it can be alphanumeric, starting with an alphabet 
character and ending in a colon. Each statement body consists of a directive, the 
"verb", combined with elements and expressions according to the syntax rules of STAR 
BASIC. 


Statements may consist of a purely blank line, a label with no body, a body with no 
label, or a label with a body. 


Labels may be numeric or alphanumeric, up to 32 characters long. Numeric labels 
are groups of digits (leading zeros are ignored), optionally followed by a colon. 
Alphanumeric labels begin with an alphabet character and end in a colon. 


Only one statement body per line is allowed, with one exception: remark statements 
may appear after (to the right of) any other type of statement. 


Statements may continue over more than one physical line. Each continuation line 
must have the continuation symbol , at the extreme left margin. 


STAR BASIC expressions are elements or combinations of elements and operators. The 
STAR BASIC elements are constants, variables, arrays and functions. They are numeric 
or string in type. Functions are further divided into utility functions, which perform 
mathematical or other internal operations, and I/O functions, which control one or 
more aspects of an input/output peripheral device (the video display or printer or disk 
files or keyboard). Functions may be further distinguished as intrinsie (part of the 
STAR BASIC language) and user-defined (created for a specific program). User-defined 
functions are written in STAR BASIC as external subroutines invoked by the use of 
the function name in an expression. 


Operators are of four types: grouping, mathematical, relational and logical. The 
grouping operators (parens) may be used to specify precedence among any and all of 
the other operators. 


2.0.3 Syntax Overview LANGUAGE 


Mathematical operators + addition, - subtraction, * multiplication, / division, \, remain- 
dering, - negation, and & concatenation combine elements to form mathematical 
expressions. The concatenation operator performs automatic value conversion to string, 
while the other mathematical operators perform automatic conversion to numeric if a 
valid transformation value is available. 


Relational operators = EQ equals, *GT greater than, <LT less than,>= = > GE greater 
than or equals, <= =< LE less than or equal, <>><NE not equals combine mathematical 
expressions to form relational expressions. They do not perform type conversion. 


Logical operators AND, OR and NOT combine relational expressions to form conditional 
expressions. 


Relational and conditional expressions are used only in conditional statements. Math- 
ematical expressions are used in many types of statements. 


Numeric constants are groups of numeric characters, optionally combined with + or 
-or . or E or an exponent; numeric values are maintained internally as 14 digit floating 
point decimal numbers in the form +.ddddddddddddddEtee (+ = plus or minus; d = digit; 
E marks exponent and e = exponent digit) in the range E+63 to E-63. 


String constants are groups of none to 16,000 characters enclosed in quotes "none, one 
or_ more characters". If quotes are used within a string literal two quotes together 
must be used '™' to represent each single quote desired. 


Numeric variables are groups of alphanumeric characters, the first an alphabetic, up 
to 15 characters long. String variables are numeric variable names followed by a 
dollar sign $. Numeric arrays are numeric variable names followed by parens; string 
arrays are string variable names followed by parens. Arrays of either type may be 
singly or doubly dimensioned. 


External subroutine names are the same as numeric variable names or numeric array 
names, while function names and user-defined function names are string or numeric 
variable or array names. 


STAR BASIC statements are of eleven types, each with a characteristic syntax. 


Null statements are blank lines, used for readibility (they take no space), and line 
labels with no bodies, used as targets of transfer statements (and serving a documentary 
purpose as well, usually). 


Comment statements are REM remark statements, used to document and label a 
program; TITLE statements, which add a title (or titles) to program listing pages; and 
LIST statements, which turn the compiler listing of the program on or off. Both REM 
and TITLE statements consist of the directive followed by the comment or title; titles 
must be string constants (enclosed in quotes), while comments need not be. REM 
statements (the symbol; is equivalent to REM) can stand alone or be added to the 
end of any other statement. LIST statements appear only in two forms: LIST ON or 
LIST OFF. 
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Assignment statements are LET (the directive is optional), which sets a variable or 
array reference on the left of an = sign equal to an expression on the right ‘performing 
type conversion if necessary and possible), and BASE, which makes an array's memory 
location the same as another variable or array's memory location, setting the two 
equal until (and unless) another BASE statement changes the array's base. Both LET 
and BASE are similar forms, LET reference = expression and BASE array AT reference 
although the LET is optional and the statement may be written simplv reference = 


expression. 


Declarative statements are DIM dimension statements, which declare a name to be an 
array, declaring its length and attributes ‘FIXED length or BASED or neither); DATA 
statements, which list constants for internal input/output; COMMON statements, which 
assign variables and arrays to the common area of memorv, which is shared among 
all routines in a program and with chained-in programs; IOLIST statements, which hold 
lists of variables and expressions for READ and WRITE statements; STOP statements, 
which halt execution; and END statements, which halt execution and compilation and 
mark the end of every routine. DIM, DATA, COMMON and IOLIST statements consist 
of the directive followed by a list separated by commas. IOLIST statements must 
have a statement label, while DATA statements often have statement labels (if thev 
are the target of a RESTORE); DIM and COMMON statements should not have statement 
labels (they may, but are only useful in the same way that labels on blank lines are 
useful). STOP and END each consist of the directive alone. STOP may appear 
anywhere in a program, while END must appear only at the end of a routine. 


Loop and conditional statements are FOR-NEXT, which frame iterated statement grouns, 
and IF-THEN, which performs a logical test to direct subsequent action, and 
IF-THEN-ELSE-ENDIF, which frame two groups of statements and direct action bv the 
result of a logical test. 


FOR-NEXT groups are similar to both single and multi-line IF-THEN's. FOR variable= 
expression TO expression STEP expression , in which: the value of the beginning 
expression is compared to the end expression, direction of the comparison being 
determined by the sign of the STEP expression (which defaults to +1 if not specifiec’, 
is similar to IF conditional expression THEN executable statement, the single line 
IF-THEN form in which the truth or falsity of the conditional expression determines 
whether or not the consequent statement is executed. Likewise, the multi-lined forms 
have obvious syntactic similarities: 


FOR variable=expression TO expression STEP expression 
° (code here executed according to loop code, iterations set by expressions) 
NEXT variable 


IF conditional expression THEN 


: (code here executed if expression is true) 
ELSE 
; (eode here executed if expression is false) 
ENDIF 
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2.0.3 Syntax Overview LANGUAGE 


Two of the transfer statements, ON GOTO and ON GOSUB, also resemble the loop 
and conditional statement forms: 


ON numeric expression GOTO statement label list [ELSE statement] 
ON numeric expression GOSUB statement label list [ELSE statement] 


In both cases, the target of the transfer is chosen by the value of the numeric 
expression (if the expression value is n, the n'th label on the list is chosen as the 
transfer target). The else clause, if used, gives an action to be performed if the 
expression value is 0 or less or greater than the number of labels on the list. In 
effect, ON GOTO and ON GOSUB are groups of conditionals based on a numeric test. 


The transfer and subroutine statements also include GOTO and GOSUB, unconditional 
transfers to a specified statement (GOSUB with the possibility of RETURN to the 
following line), CALL, which invokes an external subroutine, SUB, which heads all 
external subroutines, FUN, which heads all user-defined function subroutines (which 
return a value to the function name when used in expressions), EXIT, which returns 
values from both SUB and FUN subroutines, and CALL CHAIN, which invokes a new 
program from disk storage. 


Except for the ON GOTO and ON GOSUB forms, the syntax of the transfer and 
subroutine statements is similar: the directive, followed by a statement label or other 
expression: 


GOTO statement label 

GOSUB statement label 

CALL subroutine name |[(parameter list)] 
SUB subroutine name [(argument lst) | 
FUN function name(argument list) 


EXIT [expression 
CALL expression ilename [,disk unit number] ) 


Error handling statements are ON ERROR, which disables automatic system error 
response and substitutes an executable statement which will be performed if an error 
occurs (unless it is an I/O error trapped by the I/O error control groups within the 
1/O statement), ERROR, which invokes a specified error, and RESET ERROR, which 
disables an ON ERROR trap and returns to automatic system response. 


The syntax of the error handling statements is similar, RESET ERROR consisting of 
the directive alone, ON ERROR consisting of the directive followed by an executable 
statement, ERROR consisting of the directive followed by a numeric expression 
specifying the error number. 


Internal I/O statements are READ, which reads data from DATA statements into a 
variable list, and RESTORE, which resets the internal data pointer. Again, the syntax 
is similar, READ consisting of the directive followed by a variable list, RESTORE 
consisting of the directive optionally followed by the statement label of a DATA 
statement (default is the first DATA statement in the program). 


LANGUAGE 2.0.3 Syntax Overview 


Keyboard, video and printer I/O statements are INPUT, which reads data from the 
keyboard into a variable list, PRINT, which outputs data from an expression list to 
the video display, and WRITE, which outputs data from an expression list to the printer. 


The syntax of the three peripheral I/O statements is also similar: 


INPUT [(control list) ] variable list 
PRINT [(control list) ] expression list 
WRITE (control list) expression list 


The file I/O statements control disk files (while record I/O statements control records 
within disk files). The file I/O statements are ALLOCATE, which reserves disk space 
for new files; OPEN, which readies files for use and assigns a logical file number for 
reference; CLOSE, which ends file usage, frees the logical file number for reuse and, 
optionally, may delete the file; RENAME, which changes file names; and DATE, which 
changes the date entry in the file's directory entry. 


The file I/O statements all consist of the directive followed by a control list in parens: 


ALLOCATE (control list) 
OPEN (control list) 
CLOSE (control list) 
RENAME (control list) 
DATE (control list) 


File record I/O statements control individual records in a file. File record I/O 
statements are READ, which reads data from a record into a variable list, WRITE, 
which writes data from an expression list into a record, DELETE, which deletes 
individual records, UNLOCK, which unlocks individual records (reading a record normally 
locks it until another I/O operation on that file is performed), and REWIND, which 
resets the read pointer in sequential or ISAM files to the beginning of the file. 


Again, the syntax is similar, READ and WRITE consisting of the directive followed by 
a control list in parens, followed by an optional variable or expression list, the other 
record I/O statements consisting of the directive followed by a control list. 


READ (control list) [variable list ] 
WRITE (control list). expression list] 
DELETE (control list) 

UNLOCK (control list) 

REWIND (control list) 


The individual statement control list syntax varies, different control groups being 
allowed in different statements, but in all cases the control group syntax is similar: 


(KEYWORD=label or expressionNEXTKEYWORD=label or expression...) 


2.1 Statements and Statement Formation LANGUAGE 


The various control groups are defined in the individual discussions of the I/O statements. 
Common to all but internal I/O statements, however, is the ERL group. 


ERL=statement label 


The ERL control group acts as a within-the-statement ON ERROR trap, causing the 
labeled statement to receive control if an I/O error occurs during execution of the 
statement. 


Likewise, most file and record I/O statements allow an EOF group: 
EOF=statement_ label 


The EOF group, if used, directs action to a labeled statement if an end-of-file condition 
is encountered. 


2.1 STATEMENTS AND STATEMENT FORMATION 


Every STAR BASIC program consists of one or more routines. Routines are of two 
types: main routines and subroutines. The main routine is the control routine of a 
program. Subroutines perform tasks subordinate to the main routine. When a program 
is executed, execution begins with the first executable statement of the main program. 


Every STAR BASIC routine is composed of statements. A statement consists of a line 
of characters composing a single DX-85 variable-length record. Continuation of a 
statement is allowed: the character , must appear in the first (left-most column) 
position in each continuation line. Statements may consist of two parts: an optional 
statement label and an optional statement body. 


STAR BASIC statements are composed of labels, reserved words, constants, variables, 
arrays, functions, operators and separators. 


Deliel STAR BASIC Characters 


definition: lower case alphabetics 


abedefghijklmnoparstuvwxyz 


definition: upper case alphabetics 


ABCDEFGHIJKLMNOPQRSTUVWXYZ 
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LANGUAGE 2.1 Statements and Statement Formation 


definition: numerics 


1234567890 


definition: period 


definition; | symbols 


(blank) " $ & <> Stee PC has 986) 


definition: alphabetic 


lower _case_alphabetics 
upper case alphabetics 


definition: alphanumerics 


alphabeties 


numeries 


period 


definition: STAR BASIC characters 


alphabetics 
numerics 
period 
symbols 


The STAR BASIC characters are as defined above (see also Figure 2-1). Anv other 
printable ASCII character may be used only in string literals (See 2.2.1.2). When used 
outside of string literals, upper and lower case alphabetics are considered to be 
equivalent. 


Figure 2-1, STAR BASIC Characters 


Example: 
PRINT "Hello!" 
print "Hello!" 
Print "Hello!" 
pRiNt "Hello!" 
Example: 
COUNTER 
counter 
Counter 


cOuNtEr 


LANGUAGE 


is equivalent to 
is equivalent to 
is equivalent to 


and so on... 


is equivalent to 
is equivalent to 
is equivalent to 


and so on... 


However, "HELLO" is not equivalent to "hello": they are string literals (See 2.2.1.2). 


Figure 2-1, STAR BASIC Characters 


STAR BASIC Characters 


Alphanumerics 
Alphabetics 
Upper Case Alphabetics 
Lower Case Alphabetics 


Numerics 


Period 


Symbols 


ABCDEFGHIJKLMNOPQRSTUVWXYZ 
abedefghijklmnopqrstuvwxyz 
0123456789 


(blank) "$& < >=+-* /\0),.53 3A 


LANGUAGE 2.1.2 Statement Labels 


221.2 Statement Labels 


definition: statement label 


numerie[s ][: J 
a etic to 31 alphanumerics |: 


A statement label is either a sequence of numeric characters optionally followed by 
a colon, or an alphabetic optionally followed by up to 31 alphanumeric characters 
followed by a colon. 


A numeric label does not require a colon but an alphanumeric label does require a 
colon. A period is part of the STAR BASIC alphanumeric character set. 


Examples: 


L1000: 

Cave.canem: 

6500 

9427: 
here.there.be.bears: 
HELP.ERROR: 


Invalid examples: 


Example Comment 

x100 final colon required for alphanumerics 
x100% no special characters allowed 

x100* no symbols allowed 

100.number must begin with alphabetic if alphanumeric 


Statement labels are optional and should not be used unless needed. Each statement 
label in a STAR BASIC program occupies a small amount of internal memory when 
compiled, so labels should only be used to mark targets of transfers, RESTORE data 
points and so on. 


2.1.3 Statement Bodies 


definition: statement bodies 


reserved words 
constants 


variables 


operators/separators 
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2.1.4 Reserved Words LANGUAGE 


oO 


The optional statement body is composed of combinations for the elements listed in 
the formal definition above. The syntax of individual elements and various statements 
are defined in the appropriate subsections below. 


Only a single statement body is allowed per line. (Exception: remark statements are 
allowed after other statements.) A statement body (or statement label, if desired) 
can continue over several lines: the continuation symbol & must appear in the first 
(left-most) column of each continuation line. 


Examples: 


PRINT "This is a test" 
GOTO Cave.canem 
For I= text.1 to text.2 
print text.1*text.2 
next i 


Doubt: If realnum NE Dogstar then COUNTER=8 
ON counter Go To Taffy, Dogwood, 579,Help,Sysdem, 
helpless,cave.canem, Ulto.Error 


GOTO Initial 
2.164 Reserved Words and Built-in Functions 
WwW 
Reserved Words Function Name 
AT AND’ BASE BASED COMMON ABSOLUTE LEN BS$ 
EQ DIM CALL CLOSE DELETE ALLOCATE  DTE$ CP$ 
GE END CARR ENDIF FORMAT FUNCTION ERR CF$ 
GO EOF COPY FIXED IOLIST RESTORE IOERR LF$ 
GT ERL DATA GOSUB  KEYLEN INT FF$ 
IF FOR’ DATE INPUT PROMPT KEYLOCK TAB$ 
LE FUN’ ELSE [UNIT RECFMT POS EL$ 
LT KEY EXIT ERROR’ RECLEN VAL ES$ 
NE LET FILE PRINT RENAME STR$ FS$ 
ON LFN GOTO RESET RETURN EDIT$ CR$ 
OR NOT LIST TITLE REWIND CHAIN PF$ 
TO OFF LOCK’ WHILE STATUS ENVIRON 
OPT MODE WRITE UNLOCK CHR$ 
ORG NEXT EJECT KEYIN$ 
REC NREC ASC 
REM OPEN WIZARD 
SUB READ MACH 
STEP HRMP 
STOP FSTAT 
. USTAT 
WD 
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LANGUAGE 2.1.5 Types of Statements 


The reserved words listed above are used by the language processor to determine the 
type and function of each statement. They must not be used in other than their 
specified context (see specifie subsections below). No attempt to redefine or override 
the fixed meanings of the reserved words should be made or a compilation error will 
result. , 


Most words on the reserved list are directives or parts of directives. Some words on 
the list are operators. 

Function names are not reserved words in the strict sense. Function names will be 
treated as reserved words (and will invoke the appropriate function when used correctly) 
unless they are declared as array names in a DIM statement. In other words, the 
DTE$ function will return the date from the system clock unless DTE$ is DIM'ed; if 


DIM DTE$(50) (for instance) appears, however, DTE$ will be a string array and the 
DTE$ function will not be available. 


2.1.5 Types of Statements 
definition: statement types 


null statements 

comment statements 
assignment statements 
declarative statements 
looping statements 
transfer/subroutine statements 


error handling statements 
input/output statements 


Statement typing is done predominantly on the basis of reserved words (the directives) 
and statement syntax. The following steps summarize the STAR BASIC language 
processor statement classification process: 


1) If the statement line is blank, the statement is null. 


2) If the statement's first non-blank element is a user word (non- 
reserved word) followed by a colon, or if the statement's first 
element is a numeric constant, optionally followed by a colon, then 
a label is present and statement classification begins with the next 
element. 


2.1.5 Types of Statements 


LANGUAGE 


3) 


4) 


5) 


If the statement begins with a reserved word, the statement type 
is indicated by the reserved word. Otherwise, it is an assignment 
statement. 


If the statement does not meet any of the syntactic requirements 
of the statement type as determined above, the statement is 


reclassified as an assignment statement. 


If any statement is determined to be faulty in syntax, an error 
diagnostic is issued and processing on the statement is discontinued. 
(This may generate other error messages elsewhere in the compila- 
tion. An error in a DIM statement could leave several double- 
dimensioned arrays undeclared, for instance, or an error in a FOR 
statement would cause a NO FOR error message when the NEXT 
was encountered.) 


Expressions are of two types of two subdivisions each: 


definition: 


expression type and subtype 


mathematical 


numeric 


string 


conditional 


relational 


logical 


Mathematical expressions, whether numeric or string, consist of a numeric or string 
element optionally followed by a mathematical operator and a mathematical expression. 
Conditional expressions consist of a mathematical expression followed by a relational 
operator followed by a mathematical expression (this portion of a conditional expression 
is called a relational expression) optionally followed by a logical operator and another 
conditional expression. 


Formal definitions and additional discussion appear in the subsections which follow. 


LANGUAGE 2.2 Elements, Operators and Expressions 


Deo Elements, Operators and Expressions 


The elements of STAR BASIC are the constants, variables, arrays, and functions, the 
operators and separators which combine the foregoing and the expressions which such 
combinations create, plus the directives which define and cirect the activities of the 
language, plus the optional, user-created labels. 


Labels are discussed above; directives are discussed by statement type below. The 
rest of the elements are discussed in this subsection. 


Constants, variables, arrays and functions are separated by type: 


definition: data type 


numeric 


string 


Type is determined by the value contained (or capable of being contained) in the 
constant, variable, array or function. 


Operators are of four types: 


definition: operator type 


(grouping) 


mathematical 


relational 


logical 


The grouping operators, parens ( ), are a separate type only as a learning aid: the 
grouping operators are used with all three of the other types of operators and should 
be considered a part of each of the three sets of operators. 


Mathematical operators include the usual arithmetic operators but also include the 
string operator & (concatenation). The arithmetic operators and concatenation are 
used with both numeric and string elements; tvpe conversions are made as necessarv 
for the operation. 


The relational and logical operators are used only in conditional ‘IF-THEN...) statements. 
(Exception: the = sign is used in the assignment statement.) The relational operators 
are the arithmetic relations: equal, not equal, greater than, less than, and so on. 
The logical operators are the logical connectives: NOT, AND, OR. 


2.2.1 Constants LANGUAGE 


2221 Constants 


Constants are permanent receptacles for values. Values (also called data) are of two 
types, numeric and string. Consequently, constants are of two types, numeric and 
string. 


Dekel Numeric Constants 


definition: numeric constant 
[+]{numeric[s ]] [fraction] [E+ numericls ]] 


A numeric constant is a sequence of numeric characters (including at least one numeric 
character preceding the exponent). An optional + sign can precede the first numeric 
to indicate a positive value; a - sign must precede the first numeric if the value 
is negative. A decimal point and sequence of numeric characters (fraction) may follow 
the + or - signs or the initial numeric character(s) if present. An exponential part 
consisting of the alphabetic E followed by either an optional + sign or a - sign (required 
if the exponent is negative) followed by one or two numerics may be used as well. 


Numeric constants (and numeric values in general) must lie in the range + 


9.9999999999999E62 to + 1.0000000000000E-62. Fourteen significant places are retained 
in all numeric operations; digits beyond 14 places are truncated. 


Examples: 
45789 -76980 
.005 -.0981 
0 0 
34.87678 -9798.987 
33.44E34 -76.983E56 
290.765382 -.0234E-20 
+34.456E+34 


Invalid Examples: 


Example Comment 
1,200 commas not part of numeric constants 
E6 digit preceding exponent required 
7.9E-94 exponent is out of range 

Zsaslen String Constants 


definition: string constant 


om [printable ASCII character(s ]]" 


LANGUAGE 2.2.2 Variables 


A string constant (also ealled a string literal) is a set of double quotation marks 
optionally enclosing a sequence of printable ASCII characters. If a double quote mark 
" is desired within the sequence, it must be represented by two double quote marks: 
™, The length of a character string is the number of characters in the string (including 
blanks). The length must lie in the range 0 to the allowable length of a statement 


body. 
Examples: 


mm (null string) 

"Cacoethes scribendi" 

"THIS IS A STRING" 

"TWO QUOTES mHEREm 

“FOUR QUOTES IN A ROWz: Mitre 
(string of blanks) 


Invalid examples: 
Examples Comment 
o no closing quote 
"Two "quotes" here" contained quotes incorrectly specified 
(this is two string constants, 
"Two " and " here", invalidly coneaten- 
ated with the word quotes) 


Upper case and lower case alphabetics are not equivalent in string constants. 


Examples: 
"UPPER CASE" is not equivalent to "upper case" 
"Hello" is not equivalent to "HELLO" or "hello" 
"lower case" is not equivalent to "Lower case" or 
"LOWER CASE" 
2.2.2 Variables 


Variables are temporary receptacles for values. Since values can be numeric or string, 
like constants, variables are either numeric or string in type. 


Variables in STAR BASIC hold a single value. Numeric variables hold a single numeric 
value; string variables hold a single string value (a single character). While the value 
may change, a variable holds only one value at any time. Multi-valued variables are 
available: they are called arrays (see Subsection 2.2.3 and following). 

2.2.21 Numeric Variables 


definition: numeric variable name 


alphabetic [up to 14 alphanumeries ] 


2.2.2 Variables LANGUAGE 


A numeric variable name is an alphabetic optionally followed by up to 14 alphanumeric 
characters. Since the period . is part of the alphanumeric character set, it can be 
used to separate characters for extra readability. 


Numeric variables may not be subscripted. If a subscript is used, a numeric array 
must be used. Numeric variable names and alphanumeric labels are somewhat similar 
in construction. Identical names and labels are not allowed in the same routine: if 
a variable MonthlyTotal is used in a routine, MonthlyTotal cannot also be used as a 
line label—this will generate an error at compilation. However, MonthlyTotal and 
MonthTotal could be used together, and so on. Likewise, array and variable names 
cannot be duplicated in the same routine. 


Examples: 


x 
Gnothi.seauton 
TAXES 
Joes.net.income 
Q345.U.999 


Invalid Examples: 


Example Comment 
enumber starts with period: must start with alphabetic 
Joe's.net may not contain non-alphanumeric characters 
23.skidoo starts with a numeric 
here.there.be. tigers too many characters 
A(1) may not be subscripted 

2.2.2.2 String Variables 


definition: string variable name 
numeric variable name$ 


A string variable name is a numeric variable name followed by a $ sign. In other 
words, a string variable name is an alphabetic followed by up to 14 alphanumerics 
followed by a dollar sign. 


String variables may not be subscripted. If a subscript is to be used, a string array 
must be used. 


Examples: 
String$ 
MILLION AIRE$ 


x$ 
Joes.net.income$ 
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sd 


LANGUAGE 2.2.3 Arrays 


Invalid examples: 


Example Comment 

59.cents$ begins with a numeric 

seventy-leven$ invalid character (-) 

THIS.IS.A.SSTORAGE.AREA$ too many characters 

-String$ begins with a period 

A$(1) may not be subscripted 
2.2.3 Arrays 


An array is (in effect) a variable which references a set of values. A variable can 
be seen as a special case of an array: a variable is an array holding only a single 
value. 


Variables do not have to be dimensioned: a numeric variable holds a single numeric 
value (although that value may change, of course). A string variable holds a single 
string value (a single character, in other words). (Another way of saying this is to 
say that both numeric and string variables are automatically dimensioned at 1.) 


Arrays must be dimensioned (in a DIM statement: see Subsection 2.4.1). Both numeric 
and string arrays can be singly or doubly subscripted. Because numeric arrays reference 
individual numeric values, while string arrays reference sequences of string values 
(substrings), their syntax differs slightly and they are discussed separately in the 
subsections below. 


Subscripts in both numeric and string arrays need not be integer constants. Any 
expression which evaluates to a numeric value in the proper range may be used. The 
value will be truncated to integer. 


2.2.de01 Numeric Arrays 


definition: numeric array 
numeric variable name (subscript [ ,subscript]) 


A numeric array name is a numeric variable name followed by parens. The parens 
contain one (optionally two) subscript(s). Subscripts in DIM statements must be integer 
numerie constants. Outside of DIM statements subscripts ean be any expression which 
evaluates to a numeric value in the proper range; non-integer values will be truncated 
to integer. 


In DIM statements, the subscript(s) of an array indicate the maximum number of values 
the arrays will reference. Outside of DIM statements the subscript(s) indicate which 
value of the array is being referenced. Subscripts cannot be zero or negative: zero 
or negative subscripts generate an error. 


2.2.3 Arrays LANGUAGE 


Example: Single Subscript Numeric Array 


DIM Buneh(5) array Bunch() dimensioned at 5 values 
the five values of Bunch() are referenced: 

Bunch(1) first element 

Buneh(2) second element 

Bunch(3) third element 

Bunch(4) fourth element 

Buneh(5) fifth element 


Example: Double Subscripted Numeric Array 
DIM R(3,4) array R() dimensioned at 12 values, 3 by 4 


The values of R() are referenced: 


R(1,1) R(2,1) R(3,1) 
R(1,2) R(2,2) R(3,2) 
R(1,3) R(2,3) R(3,3) 
R(1,4) R(2,4) R(3,4) 


Array subscripts need not be integer constants. Any expression which evaluates to a 
numeric value in the proper range may be used. The expression value will be truncated 
to integer. 


Examples: 


Item(Current.stoek*3+Date(Num$)) 
Receipts(Total, Day$) 
Volume(Length*Width*Height,Item) 


Numeric arrays are always referenced value-by-value, except in DIM statements, where 
their total length is declared; or in CALL, SUB, FUN and COMMON statements, and 
function calls, where the entire array may be referenced. 


Like variable names, array names and alphanumeric labels must not match in a routine. 
If an array DailyRecord(31) is used, no label DailyRecord can be used in the same 
routine. Likewise, no array name may match a variable name in the same routine; 
A and A(7) are not allowed in the same routine or subroutine. 

2.20302 String Arrays 


definition: string array name 


string variable name [(subseript Lsubseript [;subseript]) ] 
string variable name [(starting position [,which string][;length of substring] ) | 


-) 


LANGUAGE 2.2.3 Arrays 


A string array name is a string variable name followed by parens. The parens contain 
one, two or three subscripts. Outside of DIM statements (see Subsection 2.4.1) the 
first subscript indicates the starting position of the substring. A second subscript 
following a comma indicates which string of a set of strings is being referenced. A 
second or third subscript following a semicolon indicates the length of the substring 
which is being referenced; if this subscript is not used, the substring consists of the 
characters from the starting position "rightwards" to the end of the string. If both 
comma (which string) and semi-colon (length) subscripts are used, the comma must be 
first. 


Unlike numeric arrays, a single-dimensioned string array can be referenced as a whole. 
The reference in that case is simply the string arrav name without the parens or 
subscript. 


Example: Single Dimension String Array 
DIM Array$(26) string array Array$() dimensioned at length 26 


Array$="ABCDEFGHIJKLMNOPQRSTUVWXYZ" value assigned 


Array$ value is "ABCDEFGHIJKLMNOPQRSTUVWXYZ" 
Arrav$(20) value is "TUVWXYZ" 

Array$1) value is "ABCDEFGHIJKLMNOPORSTUVW XYZ" 
Array$(537) value is "EFGHIJK" 

Array$(131) value is "A" 


Example: Double Dimension String Array 


DIM Double$(7,3) 


Double$(1,1)="1234567" 
Double$(6,2)="fgh" 


Double$(1,2;5)="abede" - 


Double$(1,3)="+/ (" 


Double$‘5,1) 
Double$(5,2) 
Double$(5,3) 
Double$(2,1;2) 
Double$(2,2;2) 
Double$(2,3;2) 


Double$‘7,1) 
double$(7,1) 
DOUBLE3$(7,1) 
COuBILE$(7,1) 


string array Double$f) dimensioned at 

3 strings of length 7 each 

values assigned to first string 
values"fg" assigned to last two positions 
of second string 

values assigned to first five positions 
of second string 

values assigned to third string 


value is "567" 
value is "efo" 
value is ")" 
value is "23" 
value is "be" 
value is "/ " 


value is "7" 
value is "7" 
value is "7" 
value is "7" 


String arravs have both maximum and current lengths. 


2.2.4 Functions LANGUAGE 


Example: 
DIM Verbatim$(100) string Verbatim$ maximum length declared 
| as 100 
’ Verbatim$="Hello" value "Hello" assigned to Verbatim$, current 


length is therefore five, the length of "Hello" 


Referencing a character position which is beyond the current length of a string array 
is a subscript error. Thus, if A$ has a current length of 5, referencing A$(7) would 
be a subscript error. This rule has one exception: such references are allowed on 
the left side of the = assignment operator. In our example above, A$(7)="string" would 
be allowed, but B$=A$(7)&" name" would not be allowed. 


Likewise, array references which start within the current length but which extend 
beyond it are also subscript errors except on the left side of the assignment operator. 
Thus, if String$ has a current length of 37, String$(30;20) would be a subscript error. 


Obviously, filling the array with spaces would eliminate such subscript errors. This: 
can be done in a number of ways, the two most common being the designation of the 
array as FIXED in length in the DIM statement, which sets its current length permanently 
to its maximum length and provides automatic blank padding on any assignment to the 
array (see Subsection 2.4.1); and the use of the general reference assignment, of the 
form A$(N)=string expression. The general reference assignment, because it references 
the entire string from N to the right end, automatically blank fills on both left and 
right as necessary to fill the string. Thus, in strings where the FIXED attribute would 
be inconvenient, an initializing statement like A$(1)="_" would fill it with blanks 
initially; a later assignment like A$=B$&Total&" credits/debits" would eliminate the 
trailing blanks for length tests. 


2.2.4 Functions 


In order to perform certain frequently used operations, a number of variable names 
have been given predetermined functions or variable values. The functions are of two 
general types: utility and input/output. 


The utility functions are of two general types: CALL CHAIN and CALL ENVIRON, 
and all the other utility functions. The CALL CHAIN statement is used to invoke a 
new main program. It is discussed in detail in Subsection 2.7.5. The CALL ENVIRON 
statement is used to obtain partition information in multi-tasking mode. It is discussed 
in detail in Subsection C.1.3 in Appendix C. The other utility functions have mathe- 
matical uses. They are discussed in detail in Subsection 2.2.4.1 below. 


The I/O functions are used with the PRINT and other I/O statements to control the 
video display or printer. They are discussed briefly in Subsection 2.2.4.2 below, in 
substantial detail in the ASCII I/O discussion in Subsection 2.10.2. 


In addition to the intrinsic funetions, STAR BASIC provides for the definition of 
additional functions. Such functions are defined in a special type of external subroutine 
headed by a FUN statement. The function names declared in FUN statements carry 
values in the same way as the intrinsic functions. The FUN statement is discussed 
in Subsection 2.7.4. 
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2.2.4.1 Utility Functions 


definition: utility functions 


LEN(string expression) 
DTE$ 


ERR 

IOERR 

INT(numeric expression) 

KEYLOCK 

POS(string expression,string expression) 

VAL(string expression) 

STR$(numerice expression) 

EDIT$(numerice expression,string expression) 

CALL CHAIN(string expression [,numeric expression] ) 


CALL ENVIRON(numeric variable,numeric variable, 


/ humeric variable,numeric variable [numeric variable]) 


CALL WIZARD(numeriec expression [string array ]) 


CALL MACH(string expression[,optional argument(,s)] ) 
CALL FSTAT(unit) 


CALL USTAT(Ifn) 


HRMP 


The LEN function returns the length of the string expression. The DTE$ function 
returns the date as an ASCII 12-digit string. The ERR and IOERR functions return 
the number of the last system and I/O error, respectively. (See Subsections 2.8.2 and 
2.10 and following for ERR and IOERR use.) The INT function returns the integer 
value of a numeric expression, truncating the fractional portion (if any). The KEYLOCK 
function returns a value of 1 if the optional security lock (F-85 option 8560) is locked, 
zero if unlocked (or if there is no security lock). The POS function gives the position 
of one string in another, zero if the sought string is not found or is longer than the 
searched string. 
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The VAL function returns the value of a sequence of numeric characters in a string 
expression. It returns the value of zero if the string expression cannot be converted 
to a numeric value. 


CALL CHAIN invokes a new program, leaving any open files open but clearing the 
current program completely before replacing it with the new program. See Subsection 
Bal eds 


CALL ENVIRON invokes an intrinsic subroutine which returns partition information 
(the number of the terminal active in the current partition, the amount of memory 
and common area available and the number of files allowed open simultaneously) and, 
optionally, allows the terminal designation to be changed. See Subsection C.1.3 in 
Appendix C for a discussion of CALL ENVIRON. 


CALL WIZARD invokes an intrinsic subroutine which establishes a 100 byte buffer in 
main memory. This buffer is used to exchange information between multi-task partitions. 
See Subsection C.1.3.2 in Appendix C for a discussion of CALL WIZARD. 


The STR$ function converts the value of a numeric expression to a string of digits. 


The EDIT$ function converts a numeric value into a specified format according to the 
value of a string expression. See Subsection 2.10.4.2 for a full discussion of EDIT$ 
usage. 


CALL MACH is used to access Optional System Support Modules (OSSM), that have New 
been loaded into memory by RUNX. The first two characters of the 2 or 3 character 

string, represent the internal name of the OSSM. The third character, if necessary, is 

an optional parameter for the desired OSSM. This is followed by optional arguments 

for the particular OSSM being accessed. 


CAUTION: If CALL MACH cannot find the OSSM specified, either because of wrong 
entry or the OSSM does not exist, the message "CALL MACH CANNOT FIND OSSM" 
will appear. Also if CALL MACH is run before RUNX is used to load an OSSM into 
memory, a RESTART error will occur. Both of these conditions are fatal, and can 
only be corrected by re-loading the system. The file name of an OSSM may be 
changed. CALL MACH will only recognize the two character internal name, and it 
cannot be changed. 


HRMP is an intrinsic numeric function with no arguments. It returns a value of zero 
if the printer is not a high resolution printer and returns a non-zero value if it is a 
high resolution printer. 


CALL USTAT is an intrinsic subroutine used to obtain logical disk unit information. 
The "unit" entry is the logical unit number for which information is desired. It will 
return a "type$" string containing the unit type specifier from CONFIG.SYS, and must 
be a non-fixed string variable. It also returns the "size", numeric, containing the 
number of blocks on the unit, and it must be a non-dimensioned numeric variable. 
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CALL FSTAT is an intrinsic subroutine that returns information about a currently open 
file. The "LFN" entry is the LFN number of the currently open file about which 
information is requested. It will return the "fmt$" string containing the file record 
format character, and must be a non-fixed string variable. 


The "type$" string contains the file type character and must be a non-fixed string 
variable. It also returns "pi", "p2" and "p3", the value of these numerics depends on 
the type of file and mode in which it was opened, according to the following chart: 


ISAM file number of 
number of records needed 
records to fill file 

type "V" file number of 

open OPT=0 blocks with 

a some data 


type "V" file allocated unused full additional 

open OPT=1 or 2 block count block count unused bytes 
in partially 
filled block 


type "F" file allocated 
open OPT=3 block count 
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Table 2-2, UTILITY FUNCTION USE . 


— 


Punetion Name Use Type 
LUE E EEE 
LEN(string 2xpression) Taxes value of ‘he .engtn Numeric 
of string expression 
OTES Takes value of he current String 


time and date in |2-cigit 
ASCII string vepresentation 


ERR Takes value of aumber of Numeric 
last non-i/O error code 
(See Subsection 2.8.2) 


fOERR Takes vaiue of aumber of Numeric 
tast /O error code See 
Supsection 2.3.2) 

NT(numeric 2xpression) Truncates qumeric vaiue Numeric 
to integer 

KEYLOCE Returns 1 if sotional Numeric 


security lock ‘s locked, 
0 if unlocked or ao lock 


?OS(string 2xpressionl, Takes value of starting Numeric 
string expression?) position of string 2xoression2 
within string expressioni, zero 
if not ‘ound 


VAListring_2xpression) Takes aumeric vaiue of Numeric 
string _2xpression, 
zero’ iF string axpression 
cannot 5e converted :2 lumeric 


STRS(numeric expression) Takes string value of String 
numeric expression 


EDITS(numeric expression, String. expression) 
ts numeric value String 


according to string 
(See EDITS Designators table) 


CHAIN(string_expression {numeric expression] ) 
“CALL CHAIN replaces current. None 
program with program whose name 
is contained in the string expression 
from disk unit numeric expression 
(default is unit 0); 
(See Supsection 2.7.5) 


ENVIRON(numeric variaple.numeric variaple.numeric variaple, 
numeric variable “.qumeric variapie}) - ao 
—. ALL = ON(ni.a2,n3,n4 (,n3 3) None 
returns multi-tasking partition 
data (See Supsection C.1.3) 


WIZARD(numeric expression [string acre) 
ALLY 'ARD, sets up a Duffer in 


main memory for partition data 
exchange in multi-user mode. 
(See Section C.1.3.2) 


HRMP Returns 0 if printer is not Numeric 
nugh resolution, @ non-zero if 
printer is high resolution. 


MACH(string_expression (,ootional ment(,s)]) 
CAuL MACH used to ACCESS 


OSSM's in memory. Two or three 
enaracter string identifying OSSM. 
with arguments if necessary. 


USTAT(unit) CALL USTAT returns type and 
size information of specified disk 
unit. 

FSTATIIEa) CALL FSTAT returns record format. 


file type and three numerics with 
file information on open file 
specified by LFN numoer. 


RD 


Note: Use of complex expressions in function calis (or, for that matter, in keyword 
control lists or loops. 2tc.) slows execution somewhat, the amount of ame 
required for evaluaung the expression oeing = ‘function of the complexity of 
the expression. 
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2.2.4.2 


definition: 


Input/Output Functions Sy 


input/output functions 


BS$ [(numerie expression) ] 

CP$(numerice expression,numeric expression) 
CF$(numerie expression) 

CS$[(numeric expression) ] 

LF$ [(numerie expression) ] 

FF$([(numerie expression) ] 

TAB$(numeric expression) 

CHR$(numerie expression) 


EL$ 
ES$ 
FS$([(numerie expression) ] LJ 


CR$[(numerie expression) ] 
PF$(numerie _expression,numeric expression) 


ASC(string expression) 
KEYIN$ 


Input/output functions are used with the PRINT statement to control output format, 
video display functions and printer control functions. See Subsection 2.10 for a detailed 
discussion of their use. 
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The BS$ function performs backspaces on the printer or video. The CP$ function does 
cursor (or printhead) positioning. CF$ changes video formats. CS$ clears the video 
sereen (or performs a formfeed on the printer) and allows video or printer font changes. 
LF$ performs a linefeed on video or printer. 


FF$ performs a formfeed on the printer, clears screen on the video. TAB$ performs 
an absolute tab to a specified column on both printer and video. CHR$ returns an 
ASCII value. EL$ erases the rest of the current line on the video. ES$ erases the 
rest of the sereen on the video. FS$ is a forward space or spaces on the video. CR$ 
is a carriage return on both video and printer. PF$ sets the printer format. ASC 
returns the numeric (decimal) ASCII code of the string character. KEYIN$ returns 
the first character found in the keyboard buffer, or null. 


262.5 Operators 


definition: operator type 


(grouping) 
mathematical 


relational 


logical 


Operators are connectors and separators. The grouping operators ‘) are used with each 
of the other types of operators and should be considered of the same type as the 
operators with which they are used. See Subsection 2.2.5.1. 


The mathematical operators are the arithmetic operators and the string operator. 
Conversion of type is automatic for values with corresponding opposites. The math- 
ematical operators are used in almost all of the statements in the STAR BASIC 
language. See Subsection 2.2.5.2. 


The relational and logical operators are used only in conditional statements. ‘Sce 
Subsection 2.6.2 for a detailed discussion of that usage. (EXCEPTION: The = sign is 
used as the assignment operator in LET statements. See Subsection 2.5.1) 


The relational operators are comparatives. At least one relational operator mv be 
present in any conditional expression. See Subsection 2.2.5.3. 


The logical operators are used to link expressions containing relational operators. Thev 
allow conjunction, disjunction and negation of relationals and the coristruction of complex 
conditionals. See Subsection 2.2.5.4. 


2.2.9 Operators LANGUAGE 


2.20501 grouping operators 


definition: grouping operators 


[expression operator] (expression) [ operator expression J 


The ( ) grouping operators separate expressions and designate the order of evaluation 
of complex expressions. Parens may be nested; such nests must not overlap. The 
expression within the innermost set of parens is evaluated first, evaluation continuing 
in order from innermost to outermost. Parens may be used with any type of operator, 
whether mathematical, relational or logical. 


Examples: 
(((a+b)*e)/((m/n)*(p+r)))*Counter Evaluation order: 
atb (1) 
(1)*e (2) 
m/n (3) 
ptr (4) 
(3)*(4) (5) 
(2)/(5) (6) 
(6)*Counter (7) 


(((Summer$&Spring$)*(Host$+Twin$))&(STR$(H.hour)&"7.89"))&" offered" 


Summer$&Spring$ (1) 
Host$+Twin$ (2) 
(1)*(2) (3) 
STR$(H.hour)&"7.89" (4) 
(3)&(4) (5) 


(5)&" offered" 


(atnumber)*Cohost=(Twin$+Host$)/R37Q4 


a+number (1) 
(1)*Cohost (2) 
Twin$+Host$ (3) 
(3)/R37Q4 (4) 
(2)=(4) 
(dth=L AND F+Fo=S)OR(NOT(d/e=r AND S=De)) 

dth=L AND F+Fo=S (1) 
d/e=r AND S=De (2) 
NOT(2) (3) 
(1)OR(3) 

Note that the parens used with the function STR$) in the second example above are ( : ) 


not operators, but part of the function name. 
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2.2.5.2 Mathematical Operators 


definition: mathematical operators 


7 addition 

7 subtraction 

* multiplication 
/ division 

\ remaindering 
& concatenation 
= negation 


The mathematical operators combine expressions and their values in a variety of ways. 
Standard mathematical conventions are used in forming expressions using the math- 
ematical operators. 


Addition combines the values of the two expressions. 

Subtraction negates the value of the second expression and adds it to the value of the 

first expression. 

Multiplication adds the value of one expression to itself the number of times designated 
by the other expression. 

Division subtracts the value of the second expression from the first successively and 
gives the number of times necessary to reach zero. 

Remaindering performs the division operation and returns the remainder (A_ B returns 
A- (B*INT(A/B))). 

Coneatenation attaches the string values of two expressions, the rightmost 
character of the first string becoming adjacent to the leftmost character 
of the second. 

Negation reverses the sign of the value of the expression. Negation is the only unary 


operator. 
Precedence: 
() first: grouping 
= second: negation 
*/\ third: multiplication, division, remaindering 
+ - fourth: addition, subtraction 
& fifth: concatenation 
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Where precedence is equal in an expression, operations are performed left to right 
within the expression. 


Operations with the mathematical operators are performed according to the rule of 
precedence shown above. First precedence operations are performed first, second 
second, and so on. If operators of equal precedence are used without parens (the 
grouping operators) operations are performed left to right within the expression. 


Mathematical operators are of two types, numeric and string. The & concatenation 
operator is the only string operator. The other purely mathematical operators are 
numeric operators. Values are converted to the appropriate type automatically, provided 
a valid transformation value is available. 


Valid transformation values are always available for conversion to string: a numeric 
expression is evaluated and the numeric value is converted to a string of numeric 
characters. 


Valid transformation values for conversion to numeric values are not always available. 
A string of numeric characters will always have a valid numeric value, but a string 
of alphabetic or other non-numeric characters does not have a numeric value and 
eannot be automatically converted. 


The grouping operators do not perform type conversion. 


If the result of an operation is assigned to a variable of the opposite type, the value 
is converted to the correct data type when the assignment is made. 


Note that automatic type conversion is only available with the mathematical operators, 
not the relational or logical operators. 


Examples: 
Example Comment 
Host$*B256 Host$ value converted to numeric, 


multiplied by value of B256; error 
message generated if Host$ not 
numeric string 


6.14+"4.5" "4.5" converted to numeric value, 
expression value is 10.6 


-7.354+"SIX" error message generated because 
"SIX" is not a numeric string 


Group$=Rservice*(tagstlistings) numeric expression on right of 
assignment operator = evaluated, 
value converted to string and assigned 
to Group$ 
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Total=Sub$&Num$ string expression on right of assignment 
operator = evaluated and converted 
to numeric, assigned to Total 


NOTE: The = when used as the assignment operator performs automatic type conver- 
sion. When = is used as a relational operator (in conditional statements), 
however, type conversion is not performed. 


2.2.5.3 Relational Operators 


definition: relational operators 


= is equal to 

EQ 
< > is not equal to 
>< 

NE 

> is greater than 

GT 

< is less than 

LT 

>= is greater than or equals 
=> 

GE 
<= is less than or equals 
=< 

LE 


Relational operators are used only in conditional (IF-THEN...) statements. (See Sub- 
section 2.6.2.) (EXCEPTION: The = assignment operator is used in assignment 
statements: see Subsection 2.5.1) 


Only one relational operator may be present in a relational expression. Consequently 
there is no order of precedence among the relational operators. 


Relational operators compare the value of the expression on the left of the operator 
to the value of the expression on the right of the operator. Data types must match 
or a compilation error will occur. Automatic type conversion does not take place. 
The VAL() and STR$() must be used to convert string values to numeric, or numeric 
values to string. 


Numeric values are compared in numeric order. String values are compared according 
to the ASCII collating sequence, using the following rules: 
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LANGUAGE 


Comparison is performed on a character-by-character basis starting 
with the leftmost character in each string. 


If a mismatch is found, the string containing the lower character 
value is considered to be the lesser. No further comparison of the 
character strings is performed. 


If both strings possess the same number of characters and all are 
equal to their counterparts, then the strings are equal. If one 
string is shorter than the other but otherwise is equal, the shorter 
string is considered to be the lesser. 


Relational operators return TRUE if the comparison matches the operator, FALSE if 
the comparison does not match the operator. 


Examples: 


Invalid Examples: 


Ny LT WAM 

" Ai} ET Ny" 
ey" Le "xyz" 
Ny" GT "xyz" 
"yx " EQ "yxy" 


X=Y 

Host NE Hostile 

Dollar$ LT Home$ 

Tackle*Guard ge Halfback/Quarterback 
Homemaker$ le Career$&Life$ 
He$&She$ ne(T*r$/Q)&Great$ 


Example Comment 
Dog$=cat*chase types must match 
Gross LE Half$&Half$ types must match 
X*Y/Z GE X*Y/Subtotal GE R23 only one relational operator 
allowed 
2.2.5.4 Logical Operators 


definition: logical operators 


AND - 


OR 


NOT 
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Logical operators are used to form complex conditional expressions. Logical operators 
are used only in conditional statements (see Subsection 2.6.2). 


The logical operators return TRUE or FALSE according to the conventional rules of 
formal logic. 


Table 2-3, LOGICAL OPERATOR TRUTH TABLES 


Expression Value 
true AND true true 
true AND false false 
false AND true false 
false AND false false 
true OR true true 
true OR false true 
false OR true true 
false OR false false 

NOT true false 

NOT false true 
Precedence: 

Grouping operators first 
Mathematical operators second 
Relational operators third 
NOT fourth 
AND,OR fifth 


Where precedence is equal (AND,OR) evaluation is done left to right within the 
expression. 
Examples Evaluation order 


x GT y AND (NOT(t=z OR t=r) OR (t=p AND e*d=g)) 


t=z (1) 
t=r (2) 
(1)OR(2) (3) 
t=p (4) 
e*d=g (5) 
(4)AND(5) (6) 
NOT(3) (7) 
(7)OR(6) (8) 
x GT v (9) 
(9)AND(8) 


2.2.5 Operators LANGUAGE 


T$ le Group$ AND NOT h$&"over" LT J$ OR f ge h$*y OR Not r*t=e*I/q 


h$*y (1) 
r*t (2) 
e*] (3) 
(3)/q (4) 
_h$&"over" (5) 
T$ le Group$ (6) 
(5)LT J$ (7) 
f ge (1) (8) 
(2)=(4) (9) 
NOT(7) 10) 
Not(9) (11) 
(6)AND(7) 12) 
(12)OR(8) (13) 
(13)OR(11) 


(Soeseet+FedInc=FedTax AND FedTaxtStateTax=TaxDuct)OR(NOT Soesec+FedIne=FedTax 
AND NOT FedTaxtStateTax=TaxDuct) 


Soesec+Fedine (1) 
FedTax+StateTax (2) 
(1)=FedTax (3) 
(2)=TaxDuct (4) 
(3)AND(4) (5) 
NOT(3) (6) 
NOT(4) (7) 
(6)AND(7) (8) 
(5)OR(8) 


The above example is equivalent to an assertion of equivalence between the two 
relations, (3) and (4). 


NOT Income GE Outgo OR Name$ EQ Mud$ 


Income GE Outgo (1) 
Name$ EQ Mudc$_ (2) 
NOT (1) (3) 
(3)OR(2) 


The above example is equivalent to an assertion of formal implication between the 
two relations, (1) and (2). 
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2.2.6 Expressions 


definition: expression type 


mathematical expression 
numeric expression 
string expression 

conditional expression 


relational expression 


logical expression 


Expressions are elements or combinations of elements and operators. 


Mathematical expressions are numeric or string elements or combinations of those 
elements with the mathematical operators. Mathematical expressions are either numeric 
or string in type, according to the type of value they hold. See Subsection 2.2.6.1. 


Conditional expressions are used only in conditional statements (see Subsection 2.6.2). 
Conditional expressions are relational expressions or combinations of relational ex- 
pressions and the logical operators. Relational expressions are combinations of math- 
ematical expressions and the relational operators. Both conditional and relational 
expressions return TRUE or FALSE as their values. See Subsection 2.2.6.2. 


2.206 Mathematical Expressions 


definition: numeric element 


numerie constant 
numeric variable 


numerie arra 
numeric function 


definition: string element 


string constant 
string variable 
string array 

string function 
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definition; mathematical expression 


pafaumerie element ]mathematical operator [mathematical expression ] 
[- string element }mathematical operator [mathematical expression 


Mathematical expressions consist of a numeric or string element, optionally followed 
by a mathematical operator followed by a mathematical expression. (Naturally, the 
grouping operators () may be used according to the normal rules of mathematics.) 


Mathematical expressions are of two types, numeric and string, according to the data 
type of their value. 


Examples: 


27 

56.907E-56 

Variable 

"Hello!" 

Variable$ 

T*host 

Roll+Item*Number/Counter 
(Trans$&Arm$*Usage&Balance$)*Index 
((April+May/F .quarter)*Indicator 
(2.95*Balance-Debit$+Credit$)& Message$ 


2.2.6.2 Conditional Expression 
definition: relational expression 


mathematical expression relational operator mathematical expression 


definition: conditional expression 


[ NOT Jrelational expression[ binary logical operator conditional expression] 


A conditional expression is a relational expression, or a relational expression preceded 
by the word NOT, or a conditional expression linked to another conditional expression 
by one of the binary logical operators, AND or OR. 


Conditional expressions are relational if they contain no logical operators, logical if 
they contain one or more logical operators. 


LANGUAGE 2.3 Comment Statements 
2.3.1 REM Statements 


Conditional expressions return the values TRUE or FALSE. They are used only in 
conditional statements. See Subsections 2.6.2. 


Examples: 


X GT Y 

Host+Dog=Active 

Great$&Brief$ LE Heart$ OR Time$&Space$ GT Joy$&Hope$ 
NOT(Tax*Penalty=T.Liability AND Interest LE Penalty)OR That$=Your$ 
soe a AND Supply=Demand)OR(Time NE Space AND Supply NE 
Demand 


2.3 COMMENT STATEMENTS 


Comment statements serve a documentary purpose only. They are not executed nor 
do they take up space at run-time. They are used to label programs, pages, subroutines 
and individual program lines. 


REM statements are the most common statements. Using one of two forms, the REM 
statement allows remarks to be inserted in programs. See Subsection 2.3.1. 


TITLE statements are used to label individual pages of the compilation printout, for 
greater programmer convenience and clearer labeling of long programs and their many 
routines. See Subsection 2.3.2. 


EJECT statements are used to separate program routines with a page eject within the 
same title. There is no need for a subtitle or new title on the following page. 


LIST statements are used to turn the compiler listing on or off. If a set of standard 
subroutines were being used with a new program, for example, the LIST statement 
could be used to suppress printout of the subroutines while the main routine and any 
new subroutines could generate normal listings. See Subsection 2.3.3. 

2.3.1 REM Statements 


definition: REM statement 


REM STAR BASIC characters 

statement REM STAR BASIC characters 

’ STAR BASIC characters 

statement’ STAR BASIC characters 

REMARK STAR BASIC characters 
statement REMARK STAR BASIC characters 


REM statements assume a variety of forms. The reserved words REM or REMARK 
or the vertical bar may begin a line or follow another statement on a line. Any STAR 
BASIC characters (the alphanumeries and symbols) may be used after the reserved 
word or vertical bar. 
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2.3.3 LIST Statements 


Examples: 


REM Initialize variables 
In.situ:REM comment with a label 
H an alternate comment form 
Erste=1 REMARK initialize variable 
rem lower case is equivalent 
remark to upper case outside 

A string literals 


2eSee TITLE Statements 


definition: TITLE statement 


TITLE "quoted literal" 


A TITLE statement consists of the reserved word TITLE followed by a double quote 
mark, followed by the page title, followed by another double quote mark. 


TITLE statements are used to insert a subtitle at the top of the page in a compiler 
listing of the program, for easier routine identification and program maintenance. The 
first TITLE statement in the program will supply the title for pages until the second 
TITLE statement is reached. The second (and each subsequent) TITLE statement will 
cause a page eject and supply a new title, which will be used until the next TITLE 
statement is reached. 


Examples: 
TITLE "Data Section" 
TITLE "Initialization One Section:" 
TITLE "Wait Message Subroutine" 
Title "File End Subroutine" 
title "Ultimate Error Recovery Routine" 


Deded EJECT Statements 


definition: EJECT statement 


EJECT 


An Eject statement consists of the reserved word EJECT alone. 


Ejeet statements are used to insert a page eject between program routines without 
the need for subtitles. The page eject is added between routines within the same 
title. 
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2.4 DECLARATIVE Statements 


2.3.4 LIST Statements 


definition: LIST statement 


LIST ON 
LIST OFF 


A LIST statement consists of either the reserved word LIST followed by the reserved 
word ON or the reserved word LIST followed by the reserved word OFF. 


LIST statements turn the compiler's printable output on or off. LIST OFF disables 
printing (or disk filing or video display of) the source program lines, symbol table and 
compiler code. LIST ON enables printing. 


Multiple LIST OFF statements with no intervening LIST ON statements have no effect 
(the listing simply stays off). Likewise, multiple LIST ON's with no intervening LIST 
OFF's have no additional effect. 


This statement's most common use is to suppress printing of external subroutines which 
are standard (and fully debugged). 


Example: 
code here (printed) 
LIST OFF 
: code here (not printed) 
LIST ON 
code here (printed again) 
2.4 DECLARATIVE Statements 


Declarative statements are not executable. Rather, declarative statements specify 
certain actions to be performed by the STAR BASIC language processor. 


DIM statements set the maximum size of numeric and string arrays. See Subsection 
2.4.1. 


DATA statements hold data (lists of constants) for internal input. See Subsection 
2.4.2. 


COPY statements cause STAR BASIC code from a routine library file to be included 
in the program when compiled. See Subsection 2.4.3. 


COMMON statements list the variables assigned to the common memory area (available 
to all routines within a program and to all chained-in programs as well). See Subsection 
2.4.4. 
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2.4 DECLARATIVE Statements LANGUAGE 
2.4.1 DIM Statements 


IOLIST statements hold lists of variables for use by READ and WRITE statements. 
See Subsection 2.4.5. 


STOP statements halt execution. END statements indicate the end of every routine 
and halt both execution and compilation. See Subsection 2.4.6. 


2.4.1 DIM Statements 


definition: DIM statement 


DIM variable name(integer [,integer }) [options ][,variable name ete... ] 


definition: | DIM options 


BASED 
FIXED 


A DIM statement is the reserved word DIM followed by a variable name (either string 
or numeric) followed by parens enclosing an integer or a pair of integers separated by 
a comma, optionally followed by either the reserved word BASED or the reserved word 
FIXED, optionallly followed by a comma and another variable name followed by parens 
enclosing one or two integers, and so on. 


DIM statements set the maximum size of numeric and string arrays. Both numeric 
and string array specifiers can be mixed in a single DIM statement. The two options 
allow the value of one array to be linked to another (BASED) or the length of a string 
array to be set at the maximum with blank padding on the right where needed (FIXED). 


With numeric arrays, the integer within the parens indicates the number of values in 
the array. If two integers are used within the parens, the array is two dimensional 
and the number of values in each dimension is specified. 


With string arrays, a single integer within the parens indicates the maximum length 
of the single string in the one dimensional array. Two integers indicate a two 
dimensional string array with the first integer indicating the maximum length of each 
string and the second integer indicating the number of strings in the array. 


BASED after the parens indicates that the value of the array will be linked to another 
array through the use of the BASE statement (see Subsection 2.5.2). BASED string 
arrays are automatically FIXED length as well. 


FIXED after the parens is only used with string arrays. It sets the current length of 
the array always equal to the maximum length declared in the DIM statement, with 
the string being blank padded on the right as necessary. Double dimensioned string 
arrays are always FIXED. The option word FIXED may be used with double dimensioned 
string arrays, but need not be. 
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LANGUAGE 2.4.2 DATA Statements 
2.4.3 COPY Statements 


If no option is specified, the array is neither BASED nor FIXED, (unless it is a 
two-dimensional string array). 


Examples: 

DIM Always$(50),Host(7),Near$(7,10),Tax(20,20) 

DIM Frank(22) 

DIM Arm$(20) 

DIM VARIABLE(10) BASED, Group$(25,10), Farm$(5) FIXED 

DIM Interest$(15) FIXED, Tax(25) BASED, Quit$(10) BASED, Log(3) 
2.4.2 DATA Statements 


definition: DATA statement 


DATA constant [,constant... ] 


A DATA statement is the reserved word DATA followed by a constant or a list of 
constants separated by commas. Numeric or string constants can be mixed as desired 
in DATA statements. 


DATA statements are used to supply values to variables in internal input using the 
READ statement (see Subsection 2.9.1). The RESTORE statement allows a particular 
DATA statement to be specified as the next point to be READ (see Subsection 2.9.2). 
Examples: 

DATA 3.14,"Pi","Zeno", 37 

DATA 10010,10101,10010 

DATA "This","that","here","now" 
Ar.thru: DATA "now is the time" 


Quasi.modor: DATA .0275934E-22 
Able.Baker: DATA "thruway","freeway","parkway",6.0275 


2.4.3 COPY Statements 


definition: COPY statement 
COPY "bookname" 


A COPY statement consists of the reserved word COPY followed by the name of a 
library routine (a "book") enclosed in quotes. 
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2.4.4 COMMON Statements LANGUAGE 


The "book" (routine) specified will be taken from the designated library file and added 
to the program during compilation. The name of the routine library to be used must 
be specified during the invocation of COMPILE or error will occur. Likewise, the 
"bookmark" and book must be correctly specified in the designated library file or an 
error will occur. For further information about library file invocation and "bookmarks" 
see Subsection 1.3. 


The COPY statement allows inclusion of already tested routines and subroutines without 
using the "Get" command during the EDIT and without recoding by hand. One or more 
library files may be created with the EDIT utility (only one may be used in any single 
compile, however), and routines from the library file may be inserted anywhere in a 
STAR BASIC program by the use of the COPY statement. 


Examples: 


COPY "SIN" 
COPY "TrigFun" 
COPY "POWER" 


Book names may be from 1 to 15 STAR BASIC symbols. Note that, like other literals, 
upper and lower case is significant in book names: "SIN" and "Sin" are not the same 
name. 


2.4.4 COMMON Statements 


definition: COMMON statement 
COMMON variable name[,variable name[,... ]] 


A COMMON statement consists of the reserved word COMMON followed by one or 
more variable names (separated by commas if there are more than one). The variable 
names can refer to single value variables or to arrays, but only the simple variable 
name is used in the COMMON statement. 


COMMON statements assign variables' and arrays' memory locations to the common 
area of memory. A partition configuration file or common size specified (see Appendix 
C) is necessary to define the amount of memory assigned to the common area; if no 
partition configuration file or common size specifier is given to RUN, no common area 
will be assigned. 


The common area of memory is accessible to all routines of a given program. In 
addition, if a new program is chained in, the common area retains the values given 
to it by the previous program. Variables present in COMMON lists are therefore not 
initialized when the program is loaded. 
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The assignment to the common area is purely by order in the COMMON list in the 
routine. No checking for data type is made. If several COMMON statements are 
used in a routine, each successive statement merely extends the list. Variable names 
can be used only once in the COMMON list. String arrays must be FIXED, and will 
take their declared length (DIM length) from the common area; numeric variables and 
arrays take eight bytes per value. 


Example: 
DIM A$(100) FIXED,B(20) 


COMMON Q,R,8,T,B 
COMMON A$ 


This example would take 292 bytes of common storage: eight bytes each for variables 
Q, R, S, and T, eight bytes for each value of B() (160 bytes), and 100 bytes for the 
100 positions in A$. 


The COMMON list of each routine is independent of all other routines within a program 
(or, in other words, the main program and each external subroutine must have its own 
COMMON statement(s) if it will use the common area). The way the common is 
defined in each routine can vary within a program, although care must be taken not 
to mix data types. 


Example: 
SUB ONE 
DIM A$(100) FIXED 
COMMON A$ 


SUB TWO 
DIM B$(50) FIXED,C$(50) FIXED 
COMMON B$,C$ 


This example uses 100 bytes of common area for A$ in SUB ONE; those same 100 
bytes are referenced as B$ and C$ in SUB TWO. 


Up to 128 variables may be active in a COMMON list. The amount of space reserved 
for the COMMON area is limited only by the amount of free memory (see Appendix 
©). ‘ 

2.4.5 IOLIST Statements 


definition: IOLIST statement 


statement label IOLIST expression[,expression[,... ]] 
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2.4.6 STOP and END Statements LANGUAGE 


An IOLIST statement consists of a statement label followed by the reserved word 
IOLIST, followed by one or more expressions, separated by commas if there are more 
than one. 


IOLIST statements hold variable or expression lists for READ and WRITE statements. 
The statement label is required to allow the READ or WRITE statements using the 
IOLIST statement to refer to it. IOLIST statements used by READ statements can 
only contain variables. IOLIST statements used by WRITE statements can contain 
variables, complex expressions, or both. (READ statements read data into the variable 
list, oT WRITE statements write the values from the expression list to the file or 
printer. 


Examples: 

Super: IOLIST A(J),3-K,B$(5;50) 

Duper: IOLIST A,B,C,D,F(20),T$ 
WRITE (LFN=5,IOLIST=Super) 
READ (LFN=9,IOLIST=Duper) 
WRITE (LFN=4,IOLIST=Duper) 

2.4.6 STOP And END Statements 


definition: STOP statement 


STOP 


definition: END statement 


END 


Both STOP and END statements consist of the reserved word alone. A STOP statement 
halts execution and sends program control to the command processor. An END statement 
also halts program execution, but an END statement also has another function: it 
halts compilation of the program as well. 


END statements may only be used at the end of routines and external subroutines. 


STOP statements may be used anywhere in a program. Every control program or 
external subroutine must end with an END statement. 
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LANGUAGE 2.0 ASSIGNMENT STATEMENTS 


Examples: 


EXIT 
END 


Stop statements may appear anywhere in a program. End statements must be at the 
end of a routine or subroutine. 


2.9 ASSIGNMENT STATEMENTS 


Assignment statements assign a value to a variable. The commonest assignment 
statement is the LET statement, which directly assigns a value to a designated variable 
(see Subsection 2.5.1). A less common but useful assignment is the BASE statement, 
which fixes an array's value as a portion of another array's value (see Subsection 2.5.2). 


2. Del. LET Statements 


definition: LET statement 


[LET] variable reference = expression 


A LET statement consists of an optional reserved word, LET, followed bv a variable 
reference (a variable name or array reference) followed by the assignment operator = 
followed by an expression. 


LET statements evaluate the expression to. the right of the operator and assign the 


value obtained to the variable or array reference on the left of the operator, converting 
to required data type if necessary. 
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Examples: 


Macavity=Mystery+Cat 

Gus=(Fire*F ore)/Fiddle 

LET Skimble$(Shanks)="Railway"&Cat$ 
Let Old$(1;4)="Deuteronomy" 

let tank=224*total 

Harp=host$é&num$ 
Grant$=9.0275*application$ 


String array references are a special case when used on the left side of the assignment 
operator. A substring reference on the left of the assignment operator blank-fills, as 
follows: If there is a gap between the beginning of the substring and the right end 
of the current value, the gap will be blank filled. If the reference is from a character 
position to the end of the string (as in A$(5)) the string will be blank-filled on the 
right as necessary to fill it to DIM'ed maximum. However, a limited length substring 
reference (A$(5;1)) would not blank fill to its right, although it would blank-fill on its 
left as necessary. 


Examples: 
DIM A$(10) 
A$="ABC" REM current length is now 3 
A$(1)=A$ REM current length is now 10, value is "ABC " 
DIM B$(5) 
B$="B" REM current length is 1 
B$(3)="V" REM current length is now 5, 
REM value is "B V " 
DIM C$(10) 
C$(331)="3" REM length is now 3, value is " 3" 
C$(531)="5" REM length is now 5, value is" 3 5" 
C$(7)="7" REM length is now 10, value" 35 7 " 


However, subscript references to the right of the assignment operator for in any other 
type of STAR BASIC statement) do not blank-fill to the maximum length of the string 
(unless the string array is declared FIXED in its DIM statement). Substring references 
outside of the left hand of the assignment statement fill onlv to the current length 
of the string array. An attempt to READ or INPUT to a substring beyond the current 
length of the array will generate a subscript error. 


2.562 BASE Statements 


definition: BASE statement 


BASE based array name AT array reference 
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A BASE statement consists of the reserved word BASE followed by the name of the | 
array being assigned, followed by the reserved word AT followed by an array reference. 


When a string or numeric array is declared BASED in its DIM statement, no internal 
memory space is allocated to that array. Instead, the BASED attribute indicates that 
the array is to share space with some other array. The array reference in the BASE 
statement specifies the first internal memory location of the based array. 


Example: 


DIM A$(100),B$(70) BASED 
BASE B$ AT A$(31) 


B$ would then take the substring of A$ from character 31 to character 100 as its 
value. 


Variables ean be BASED as well as arrays: they must be DIM'ed as single value arrays, 
BASED, then used in a BASE statement as a normal, based array. 


A based array can be re-based as often as desired. A based array must be based on 
an array of matching type, however: no conversion is mace. 


Caution must be used to see that the array portion following the array reference is 
long enough to fill the based array with values or pseudorandom values will fill the 
based array beyond the end of the basing array. (In fact, the values of the based 
array beyond the end of the basing array will be the values of whatever variables are 
stored in the internal memory locations after the end of the basing array.) In addition, 
the current length of string arrays referred to by a BASE statement's array reference 
must exceed the position referenced or a subscript error will result. 


Examples: 


DIM A$(100),B$(70) BASED, Array(20), B.array(10) Based, Ch$‘50,5) 
DIM T$(20,5) Based 


BASE B$ AT A$(31) 
Base B.array at Array(11) 
Base T$ at Ch$11,1) 
Base B$ at Ch$(5,3) 


In the examples above, the array B$ is set equal to the last 70 characters of A$ in 
the first BASE statement, and is set equal to the seventv characters beginning at the 
fifth character of the third string of Ch$ in the last BASE statement. A$ must have 
a current length of at least 31 and Ch$'s third string must have at least five characters 
or a subscript error would result. In addition, A$ must have a current length of 190 
or B$ will contain pseudorandom values for all positions beyond the current length of 
A$ (Ch$ would not present this problem, since as a two dimensional string arrav, it 
is automatically FIXED length). In the second BASE statement, the ten references of 
the numerie array B.arrav are set eaual to the ten references of Arrav starting at 
Array(11). 
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2.6 LOOPS AND CONDITIONALS LANGUAGE 
2.6.1 FOR-NEXT Statements 


In the third example, the two-dimensional array T$ is set equal to the values of Ch$ 
starting at Ch$(11,1). Note that T$ is not set equal to the 11th position substring of 
CH$ for each of Ch$'s five strings, but rather, T$(1,1) to T$(20,1) are set equal to 
Ch$(11,1) ‘to Ch$(30,1), T$(1,2) to T$(20,2) equal Ch$(31,1) to Ch$(50,1) and so on. 


2.6 LOOPS AND CONDITIONALS 


Program loops are used to conduct iterated and stepped operations automatically. 
Conditional statements are used to conduct tests and direct execution according to 
the results of those tests. 


FOR statements open program loops, designating the initial value of the index variable, 
its end value and optionally, what change will be incremented upon each interaction 
of the loop. NEXT statements close loops, sending control to the associated FOR 
statement for evaluation of the index variable, repeating the loop if the variable is 
within the initial-end parameter bounds, continuing the program with the statement 
following the NEXT statement if the parameters are exceeded. See Subsection 2.6.1. 


IF-THEN statements test conditions, executing a statement or series of statements if 
the condition proves true. An optional ELSE can be used to set a statement or series 
of statements to be executed if the condition proves false. If the extended form is 
used, an ENDIF statement is used to close the conditional series. See Subsection 2.6.2. 
2.6.1 FOR-NEXT Statements 


definition: FOR statements 


FOR numeric variable = numeric expression TO numeric expression 


A [ STEP numeric expression ] 


definition: NEXT statement 


NEXT numeric variable 


A FOR statement consists of the reserved word FOR followed by a numeric variable 
name followed by = followed by a numeric expression followed by the reserved word 
TO followed by another numeric expression followed optionally by the reserved word 
STEP followed by a third numeric expression. 


A NEXT statement consists of the reserved word NEXT followed by a numeric variable 
name. The variable name must match the variable name used in a preceding FOR 
statement (but not necessarily the FOR statement immediately preceding: see below). 


The operation of a FOR-NEXT loop is as follows: 
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Cy) 


Example: 


For I=X1 TO X2 STEP X3 


loop code 

Next I 

1) the index variable I is assigned the value of the first expression, 
X1 

2) the value of I is compared according to the value of the step 


expression, X3 

a) if X3 is positive, then if I is greater than the endpoint 
expression, X2, the loop code (the executable statements 
between the FOR... and the NEXT statements of the loop) 
is not executed and program execution continues at the first 
statement following the NEXT statement. 

b) If X3 is negative, then if I is less than the value of X2 the 
loop _code is not executed and execution continues at the 
statement following the NEXT statement. 

¢) if neither a) or b) is true, the loop code is executed. 

3) after the loop code is executed the NEXT statement adds the value 

of the step expression, X3, to the current value of I. 

4) step 2) is repeated 


Example: 
Cy 


FOR I=10 TO 1 STEP -2 
A(1)=0 
NEXT I 


In this example, the index variable I would be set to 10 upon loop entry, A(10) would 
be set to 0, -2 would be added to I making I=8, I would be compared to 1 and found 
to be greater, loop execution would continue since -2 is negative, A(8) would be set 
to 0, -2 would be added to I making I=6, I would be compared to 1 and found to be 
greater, A(6) would be set to 0, -2 would be added to I making I=4, I would be compared 
to 1 and found to be greater, A(4) would be set to 0, -2 would be added to I making 
I=2, I would be compared to 1 and found to be greater, Af2) would be set to 0, -? 
would be added to I making I=0, I would be compared to 1 and found to be less than, 
loop execution would halt and program control would pass to the line following the 
NEXT I. 


If the optional STEP expression of the FOR statement is omitted, the step value is 
+1. 


Example: 
For Counter=0 to 9 


Number$(Counter+1;1)=Counter 
Next Counter 


2.6.1 FOR-NEXT Statements LANGUAGE 


In this example the index variable Counter would take the initial value 0 and increase 
by 1 until Counter exceeded 9. For each successive value of Counter, the string 
Number$ would be filled, one single-character substring Number$(Counter+1;1) for each 
value of’ Counter. The Counter+1 expression in the substring is necessary to avoid 
reference to the non-existent position 0 in the string. This simple loop fills the first 
ten positions in the string Number$ with the numeric characters. When the value of 
Counter exceeds 9, program execution continues following the Next statement. 


Increments and ranges of the index variable of a FOR-NEXT loop need not be integer. 
Example: 


FOR Variable=.0275 to -7.34E22 step -3.0278E4 
Decrement=Decrement+Variable 
Next Variable 


This example would set Variable equal to .0275 and add -3.0278E4 at each iteration 
until -7.34E22 is exceeded, adding Variable to Decrement each time. Since this loop 
would iterate more than 2 quintillion times (2E18), its use in working programs is not 
recommended. 


Transfers may occur within and from a FOR-NEXT loop. Transfers may not be made 
into a loop unless the transfer is a return from a transfer out of the loop. 


Example: 


Data.check: For i=1 to 50 

If A(i)=0 then goto Data.error 
End.d.cheek: Next i 

Return 
Data.error: Print "A(",i,")=0" 

goto End.d.check 


In this example, the values of A(i) are checked for i from 1 to 50. If any A(i)=0, the 
Print statement at Data.error will display the error message on the video displav and 
the goto will continue the loop. When i exceeds 50, control passes to the Return 
statement, which sends execution back to the main routine. 


Example: 


A=0 
For I=1 to 100 
J=I 
If I LT 27 then go to Bypass 
J=J+100 
Bypass: A=A+T(J) 
NEXT I 
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In this example, the holding variable A is filled with the values of T(J) from T(1) to 
T(26) and from T(127) to T(200). A logie test sends control to Bypass for I less than 
27, while control drops through the logie test for I equal 27 or greater, where J is 
incremented by 100 before Bypass is reached. 


While control can transfer out of a loop, or within a loop, or out of a loop and then 
back in, control cannot transfer into a loop. 


Invalid example: 


Goto Inside 

For I=5 to 15 
Inside: Table(I)=I*Table(I-1) 

Next I 
The invalid example shows a goto jumping to the center of a loop. Since the variable 
I would not have been initialized, an error would result. 


Loops can be nested. Index variables cannot be duplicated within a nest of loops. 
Loops in a nest cannot overlap: each interior loop must be completely contained in 
the loop immediately exterior to it, must completely contain any loops interior to it. 


Example: 

For I=1 to 10 

For J=1 to 5 

For K=1 to 7 

Digit $(I+K-1,J;K)=I*J*K 
Next K 

Next J 

Next I 


In this example, three nested loops are used to fill a complex string with digits. Loop 
K is within loop J which is within loop I. 


Invalid example: 


For I=1 to 10 

For J=1 to 5 

For K=1 to 7 
Digit$(I+K-1,J;K)=I*J*K 
Next J 

Next K 

Next I 


In the invalid example, the Next J and Next K statements have been transposed and 
the J and K loops overlap. Since the Next J would send control to the For J... 
statement and the For K statement would then be encountered a second time with no 
Next K statement intervening, an error would result. 


2.6.2 [F-THEN-ELSE-ENDIF Statements | LANGUAGE 


The range and step parameters can be varied in the loop. 
Example: 


For I=1 to 100 
I=I*J 

A(I)=I/J 

I=I/J 

NEXT I 


In this example, the index variable I is varied in value within the loop, then returned 
to its incremented value before repeating the loop. Variations can be even more 
complex. 


Example: 
For Index=Quantum*Value To Harbinger/(Hope-Charity) Step Index 
If Index GT Quantum*Value Then Value=Index/Harbinger 
Hope= Value*Index 
Index=Index + 1 
Next Index 


In this example, the index variable Index and the three expressions of the For Index... 
statement vary within the loop. 


2.6.2 IF-THEN-ELSE-ENDIF Statements 


definition: IF-THEN statement 


IF conditional expression THEN statement 


In its simplest form, an IF-THEN statement consists of the reserved word IF followed 
by a conditional expression, followed by the reserved word THEN followed by a 
statement. The statement must not be a declarative statement or a FOR statement, 
or a NEXT statement. 


If the conditional expression tests TRUE, the statement is executed. If the conditional 
expression tests FALSE then the statement is not executed and control pases to the 
next line (drops through). 


definition: .IF-THEN-ELSE-ENDIF statements 


ELSE 
[statementl s ] ] 
ENDIF 


IF conditional expression THEN 
en [s ] ] 
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In its full version, the IF-THEN statement group consists of the reserved word IF 
followed by a conditional expression, followed by the reserved word THEN on the first 
line, one or more statement lines following the IF... line, an optional line containing 
only the reserved word ELSE followed by another series of statement lines followed 
by a line containing only the reserved word ENDIF. 


In the multi-line form, the conditional expression is tested TRUE or FALSE. If it is 
true, the statements following the IF statement are executed. If it is false and there 
is no ELSE statement, program control passes to the line immediately following the 
ENDIF statement. If it is false and an ELSE statement is used, the statements 
following the ELSE statement are executed. Whether TRUE or FALSE with an ELSE 
statement, after the appropriate statement lines are executed, control passes to the 
line following the ENDIF statement. 


Examples: 


IF x GT y then goto 555 
IF Host$ GE Guest$ Or Half$ NE Whole$(5;5) Then Use$=Bad$ 
If Not G=F*E or G=F/E Then F=0 
If Arm$ GT Strong$ Then 
Rack$=Hold$&Half$ 
For I=1 to 10 
Vary(I)=Rack$*10 
Next I 
ELSE 
6 Rack$=Half$&Half$ 
For I=10 to 1 Step -3 
A(I)=0 
Next I 
7 ENDIF 
8 : 


oP WN FR 


In the example at line 1, the conditional x is greater than y is tested. If it is true, 
control passes to line 555; if false, control passes to line 2. In the example at line 
2, the complex conditional is tested. If Host$ is greater than or equal to Guest$ or 
if Half$ is not equal to Whole$(5;5) then Use$ is set equal to Bad$ and control passes 
to line 3; otherwise Use$'s value remains at its present value and control passes to 
line 3. 


In the example at line 3, if G is not equal to F*E or if G equals F/E then F is set 
equal to 0 and control passes to line 4; otherwise control simply passes to line 4 with 
no other action. 


In the example at line 4 and following, if Arm$ is greater than Strong$ then the lines 
at 5 and following are executed, the ELSE statement and the lines following 6 are 
skipped and execution continues at line 8. If Arm$ is not greater than Strong$, the 
lines at 6 and following are executed. 


2.6.2 IF-THEN-ELSE-ENDIF Statements LANGUAGE 


Although declaratives, loops and further conditional statements are not allowed as 
consequents of the simple form of the IF-THEN statement, they are allowed as 
consequents of the multi-line form. If conditionals or loops are used as consequents 
of the multi-line form, each such group of statements must be complete within the 
IF or ELSE statement block. 


In the example labeled line 4 and following, above, two FOR-NEXT loops are used, 
one in the IF consequents and one in the ELSE consequents. Nests would be allowed 
in the same positions. 


Example: 


If groat NE groats then 
For Index=Norm to tophat 
if groat LT groats then 
Lesser: Apple(Index)=groats*Index 
Apple(Index+tophat)=groat*Index 
ELSE 
Greater: Apple(Index)=groat*Index 
Apple(Index+tophat)=groats*Index 
ENDIF 
Next Index 
Else 
Equals: For Index=Norm to tophat 
Apple(Index)=groat*Index 
Apple(Index+tophat)=Apple(Index) 
Next Index 
Endif 


In the example above, a FOR-Next loop is contained in the IF consequents and another 
FOR-NEXT loop is contained in the ELSE consequents. Another IF-THEN-ELSE group 
is contained in the loop in the IF consequents. If groat is not equal to groats, then 
it is either less than or greater than groats. If it is lesser, the operations beginning 
at line Lesser insert a set of values in the array Apple. If it is greater, the operations 
beginning at line Greater insert values in Apple. If groat equals groats, the ELSE 
consequents of the external IF-THEN (beginning at Equaiz) insert values in Apple. The 
internal IF-to-ENDIF group If groat LT... is entirely contained in the FOR-NEXT loop 
that is the IF consequent of the exterior IF-ENDIF group If groat NE... . A second 
FOR-NEXT loop begins at Equals and constitutes the ELSE consequents of the exterior 
IF-ENDIF group. 


Unlike loops, transfers are allowed freely into and out of IF-ENDIF groups. 


Example: 

If y NE z then 
Roast=z*number 
Road=y*number 
Goto Hope 
Else 
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Elsie: Roast=z 
Road=Roast 
Endif 
Hope: Raffle(1)=Roast 


Raffle(Roast)=Road 
Raffle(Road)=z 
Raffle(z)=y 

Goto Elsie 


In the example above, the Goto in the If consequents sends control first to the 
subroutine Hope and then to the Else consequents at Elsie and following. 


Example: 
If Home$=Heart$ Then 
Goto String 
Else 
Hopeful$=Hard$& Hardart$ 
String: Trans$=N on$&Stop$ 
Endif 


In the above example, the transfer Goto String in the If consequents sends control to 
the last statement of the Else consequents. 


Example: 
Goto Inside 


If q=t then 
Trots=trans+stops 
Inside: Harp=string+s 
Else 
Trots=run+s 
String.s=H+arp 
Endif 


In the example above, a transfer before the IF-THEN sends control to Inside, the 
second statement of the IF consequents. After executing Inside, the Else switches 
control to the line following Endif. 


2.4 TRANSFERS AND SUBROUTINES LANGUAGE 


Example: 


If Group$=Hope$ Then 
Drop=Drip+droop 
Goto Donner 
Else 
Hap=Hop-ota 

Endif 


Donner: y=f*¥z+t 
Goto Blitzen 


In this example, a goto in the IF consequents sends control to an external routine, 
which then sends control to a location not shown. 


2.7 TRANSFERS AND SUBROUTINES 


Program flow in STAR BASIC is normally line by line, in consecutive order from first 
line to last. The conditional statements and loops of the preceding subsection interupt 
this consecutive order temporarily, but consecutive execution resumes following the 
Next or Endif. 


Transfer and subroutine statements allow program control of program flow in a variety 
of ways. 


GOTO statements transfer program control to a designated line. GOSUB statements 
transfer control to a designated line with the potential of a RETURN bringing control 
back to the line following the GOSUB. ON...GOTO and ON...GOSUB in effect act as 
multi-valued switches, or groups of IF-THEN's, sending program control to a variety 
of designated lines under the control of a numeric variable. Routines following a 
GOSUB or ON...GOSUB are called internal subroutines, or local subroutines. 


Another group of statements allows transfer of control to externally compiled routines 
called external subroutines, or non-local subroutines. CALL statements send control 
to an external subroutine. A SUB statement heads each such external subroutine. 
CALL statements may optionally pass parameters to subroutines through SUB statements. 
Another type of external subroutine is called a function subroutine. Function subroutines 
are headed by a FUN statement, which contains the function name. The function 
name both invokes the subroutine and returns a value to the expression within which 
it is used. EXIT statements in both external and function subroutines return values 
to the calling routine and send program control to the line following the CALL statement 
which invoked the subroutine. 


CALL CHAIN statements invoke an entirely new main program, leaving open any open 


files but clearing all variable values and program and entering the new program, which 
then runs from its beginning. 
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The COMMON statement may be used to assign variables to a common area in memorv. 
The common area is accessible to all routines in a program. It is also maintained 
when a new program is chained in. Use of the common area thus allows data to be 
passed to external subroutines or new programs in addition to the subroutine parameter 
pass and file I/O. See Subsection 2.4.4 and Appendix C. 


Bel GOTO Statements 
definition: GOTO statement 


GOTO statement label 
GO TO statement label 


A GOTO statement consists of the reserved word GOTO for the reserved words GO 
TO) followed by a statement label. 


GOTO statements send program control to the line designated. Such transfer points 
must be within the local routine and must not be the interiors of loops unless the loop 
has been initialized. 


Examples: 
Goto 100 
GOTO Hold 
GOTO In.situ 
goto heres.help 
Goto ER.routine.3 
Deleon GOSUB And RETURN Statements 


definition; GOSUB statement 


GOSUB statement label 


definition: RETURN statement 


RETURN 


A GOSUB statement consists of the reserved word GOSUB followed by a statement 
label. The form GO SUB is not an allowable usage, in part because SUB is usec to 
mark external subroutines. 


A RETURN statement consists of the reserved word RETURN. 


2.7.2 GOSUB and RETURN Statements LANGUAGE 


A GOSUB statement sends control to the line designated. Program execution continues 
normally at that point until a RETURN statement is encountered. When RETURN is 
encountered, program control resumes at the line following the last GOSUB. 


The target lines of a GOSUB are called an internal subroutine or a local subroutine. 
Local subroutines can be as long as desired, within normal program restraints. Local 
subroutines can be nested, or stacked. When a RETURN is encountered, control resumes 
following the most recent GOSUB. In other words, the RETURN locations are "stacked"; 
each successive GOSUB adds a location to the top of the stack and each RETURN 
removes the top item from the stack. Up to 50 locations can be stacked (or in other 
words, up to 50 subroutines can be successively nested). 


Example: Program flow: Current Return 
(after execution) 
pl: Gosub gl pl: to gl p2 
p2: main routine gi: to dl g2 
continues di: Addum=time*rate g2 
‘ d1.1: Return (to g2) p2 
R g2: to g3 g3 
. g3: to d2 g4 
gl: Gosub dl d2: to g4 d2.1 
£2: Gosub g3 g4 to d3 ri 
g3: Gosub d2 d3: subtotal=current+Addum ri 
g4: Gosub d3 d3.1: Return (to r1) d2.1 
ri: Return ri: Return (to d2.1) g4 
d2.1: current=subtotal+current g4 
dl: Addum=time*rate d2.2: Return (to g4) g3 
d1.1: Return g4: to d3 rl 
d2: Gosub g4 d3: subtotal=current+Addum rl 
d2.1: subtotal=current+Addum d3.1: Return (to r1) g3 
d2.2: Return ri: Return (to g3) p2 
d3: current=subtotal+current g3:. to d2 g4 
d3.1: Return d2: to g4 d2.1 
g: to d3 rl 
. d3: current=subtotal+current rl 
, d3.1: Return (to r1) d2.1 
ri: Return (to d2.1) g4 
d2.1: subtotal=current+Addum o4 
d2.2: Return (to g4) p2 
g4: to d3 rl 
d3: current=subtotal+current rl 
d3.1: Return (to r1) p2 
ri: Return (to p2) — 
p2 ‘ee 
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ry 


Stacking: 
ri 
d2.1 2.1 d2.1 rl 
— g4 g4 g4 = =g4 g4 rl d?2.1 2.1 d2.1 
g2 _g3 gs g3 gs g3 g3 g3 g3 g3 g4 g4 g4 g4 g4 


p2 p2 p2 \p2 p2 p2 p2=—p2 p2 p2 p2 p2 p2 p2 p2 p2 p2 p2 


rl 
p2 p2 p2 


In the example above, a set of gosub's first initializes a variable Addum, then performs 
a group of iterations on the two assignments subtotal=current+Addum and current=sub- 
total+current. The sequence of execution is shown under the heading Program flow:, 
the Return location at the top of the stack after each line is executed as shown under 
the heading Current Return:. The sequence of "stacks" as the program is run is shown 
under the heading Stacking:. 


2.7.3 ON...GOTO, ON...GOSUB Statements 


definition: ON...GOTO statement 


ON numeric expression GOTO label list [ELSE statement ] 
( ) ON numeric expression GO TO label list [ELSE statement ] 


definition: ON...GOSUB statement 


ON numeric expression GOSUB label listLELSE statement ] 


An ON...GOTO statement consists of the reserved word ON followed by a numeric 
expression followed by the reserved word GOTO (may be written GO TO) followed by 
a list of statement labels separated by commas, optionallv followed by the reserved 
word ELSE followed by an executable statement. 


ON...GOSUB statements follow the same form, with the reserved word GOSUB replacing 
the reserved word(s) GOTO (GO TO). 


ON...GOTO statements act as a multi-value switch equivalent to a set of IF-THEN-GOTO 
statements. The numeric expression is evaluated and truncated to an integer value I. 
The I-th label on the label list is then taken as the target line of the GOTO. If the 
optional ELSE is used, the statement following the ELSE is executed if the numeric 
expression value is less than one or greater than the number of items on the label 
list. If the optional ELSE form is not used, control drops through if the expression 
value is less than one or greater than the number of labels on the list. 
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ON...<GOSUB statements are used the same way as ON...GOTO statements except that 
a GOSUB is performed rather than a GOTO. 


Examples: 


On alpha Goto Rand,Quasi,Norko,Hopi,Er.rr 

On Variable GOTO 1,2,3,4,5,6,5,5,4,3,4,5,6,6,6,5,3,3,4,3 ELSE GOTO Help 
ON Switch.value GO TO high, low, medium, off ELSE Print "Program Error" 
on j gosub alpha,beta,gamma,delta 


In the last example above, the on j gosub... statement is equivalent to a group of 
IF-THEN's: 


j=1 then gosub alpha 
j=2 then gosub beta 
j=3 then gosub gamma 
j=4 then gosub delta 


In this example, if j falls in the range 1 to 4 then the appropriate gosub would be 
executed. If j is less than one, or greater than four (truncated value), then execution 
would simply drop through and continue on the following line. 


In the example On Variable... if the range of Variable falls between 1 and 20, one of 
the line labels shown (1 through 6) will be picked as the target of the GOTO. If 
Variable's truncated integer value falls below 1 or above 20, the statement following 
the — will be executed and execution will continue at the line labeled Help (not 
shown 


The optional ELSE predicate can be particularly useful in ON...GOSUB's, since most 
internal subroutines return to the main routine after only a few lines. The ELSE 
predicate can be used to direct execution to prevent execution on the following line 
if the GOSUB is not performed. 


Example: 
For index=0 to 9 
Transformer(index+1)=index 
On index gosub 1,2,3,4,5,6,7,8,9 ELSE Goto Next.Index 
Alpha(index)=Group 
Next.Index: next index 


1 Group=N$&R $(index;index) 
Return 

2 Group=M$&R $(index;index) 
Return 
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3 Group=0$&R $(index;index) 
Return 

4 Group=256 
Return 

5 Group=R $(index) 
Return 

6 Group=N$&R $(index;1) 
return 

7 Group=M$&R $(index;1) 
Return 

8 Group=512 
Return 

9 Group=Alpha(1)& Alpha(2) 
Return 


In this example, the ELSE predicate is used to avoid the drop through in the initial 
run through the loop. When index=0, the array Transformer is given a value, but the 
On index Bos ibe switch would drop through to set Alpha(0) equal to Group, generating 
an error, if the ELSE had not been used. Since the Goto following the ELSE directs 
transfer to the next index statement, the Alpha(0) line is not executed and the loop 
continues. Successive values of index then call gosub's to lines labeled 1, 2 and so 
on, where values of Group are acquired. The Return's following each numbered line 
then send execution back to the loop, where Alpha(index) is given a value and loop 
execution continues. 


2.7.4 CALL, SUB, FUN, EXIT Statements 


definition: subroutine name 


numeric variable name 
alphabetic to 14 alphanumerics | 


definition: function name 


variable name 
alphabetic [up to 14 alphanumerics] [$] 


A subroutine name is formed the same way as a numeric variable name: an alphabet 
character, optionally followed by up to 14 alphanumeric characters. 


A function name is formed the same way as a variable name: an alphabet character 
optionally followed by up to 14 alphanumeric characters, optionally followed by a dollar 
sign $. 


2.7.4 CALL, SUB, FUN, EXIT Statements LANGUAGE 


Subroutine names are used to identify external subroutines (headed by a SUB statement) 
and to invoke them (with a CALL statement). Function names are used to identify 
and invoke user-defined functions. Functions are written as external subroutines, but 
are invoked by the use of the function name in an expression in a calling program. 


Examples: Comment: 
Power subroutine name or function name 
Ho.Ho.ho subroutine name or function name 
Er.handler.1 subroutine name or function name 
Help.is.at.hand subroutine name or function name 
Q67R27 subroutine name or function name 
Dart$ function name 
Home$ function name 
Help.is.at.hand$ function name 


definition: CALL statement 
CALL subroutine name [(parameter list) ] 
definition: SUB statement 


SUB subroutine name [(argument list)] 


definition: CALL parameter list 


expression [,expression [s, ]] 


definition: SUB argument list 


variable name [,variable namels, |] 


A CALL statement consists of the reserved word CALL followed by a subroutine name, 
optionally followed by a parameter list in parens. The parameter list consists of one 
or more expressions, separated by commas if more than one. 


A SUB statement consists of the reserved word SUB followed by a subroutine name, 


optionally followed by an argument list enclosed in parens. An argument list consists 
of one or more variable names, separated by commas if more than one. 
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A CALL statement invokes the subroutine named. If the optional parameter list is 
used, the values of the expressions (which may be numeric or string constants, variables, 
arrays, or complex expressions) are passed to the subroutine invoked. 


A SUB statement begins each external subroutine, identifying it to the ealling program. 
If the optional argument list is used, values from the parameter list of the calling 
statement are inserted in the variables of the argument list. 


Values are passed from the parameter list to the argument list purely by order. The 
number of items in each list must be the same, and the data type of each expression 
and the data type of the corresponding variable must match, or an error will result. 
If numeric or string arrays are passed, each array must be dimensioned in a DIM 
statement in the subroutine before use. 


Data can also be made available to SUB subroutines through the COMMON area (see 
Subsection 5.4.3). 


Examples: 
CALL T.Sub(Arnold,"Hello! ",7.045E27,Dave$) 
Call Backfield(Righthalf,Lefthalf,Full,Quarter,Tail) 
Call Kitchen(Stove(7,9),Pot$(6;10),Salt*Pepper) 


Fred: Call Fred 
END 
SUB Kitchen(a,b$,c) 
DIM b$(10) 
a=b$*e 
Exit 
End ‘ 
SUB Backfield(r,l,f,q,t) 
For index=r to 1 step f 
q=t*indextq , 
next index 
exit 
end 
SUB Fred 
E=Err 
Print "Error number",E 
Print "CALL KEY OPERATOR" 
STOP 
Exit 
End 
SUB T.Sub(a,b$,¢c,Dave$) 
DIM b$(20),Dave$(25) 
Dave$=b$&ate 
Exit 
End 
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In the example above, four external subroutine calls are illustrated. Fred is an ultimate 
error handling routine which does not pass values to the subroutine. T.Sub, Backfield 
and Kitchen do pass values. T.Sub's call passes the value of the numeric variable 
Arnold to the. numeric variable a; the value of the string constant "Hello! " to the 
string array b$; the value of the numeric constant 7.045E27 to the numeric variable 
e; and the value of the string array Dave$ to the string array Dave$. T.Sub assigns 
a new value to Dave$ and that value (with the unchanged values of the rest of the 
parameters) are passed back to the calling program. 


Backfield's Call passes five numeric values, from the numeric variables Righthalf, 
Lefthalf, Full, Quarter and Tail, to the five numeric variables r, 1, f, q and t. The 
first three parameters are used to structure a loop, which then uses the values of the 
last two parameters in the iteration to change the value of the fourth variable, q. 
After completing the loop, the new value of q is passed back to the calling program, 
where it is stored in Quarter. The other parameter values are returned unchanged to 
the calling program. 


Kitchen's Call passes three values, the value of the array reference Stove(7,9) to the 
numeric variable a; the value of the string array reference Pot$(6;10) to the array b$ 
and the value of the numeric expression Salt*Pepper to the numeric variable ec. Although 
the value passed to the numeric variable a is from an array reference, only the single 
value is passed and the variable a is used only as a simple numeric variable in the 
subroutine, so the variable a is not dimensioned within the subroutine. The values 
passed to the array b$ require an array to receive them, and the array b$ is used as 
an array within the subroutine so b$ must be dimensioned within the subroutine. 
Kitchen uses the second and third parameters to change the value of the first; the 
new value of the numeric variable a is passed back to the calling program upon the 
exit from the subroutine, where it is stored in the array reference Stove(7,9). The 
values of b$ and ¢ are returned unchanged to the calling program. 


Whether string or numeric, if an entire array is to be passed to an external subroutine, 
it is referenced by the variable name portion of its name in both CALL and SUB 
statements. 


For instance, an array Numbers(X,Y) would be referenced by Numbers in the CALL 
statement and by Numbers or Numeric or some other numeric array name portion in 
the SUB statement. 


If an array reference (that is, a single value) is to be passed, it is referenced normally 
in the CALL statement (e.g., Numbers(1,7)) and referenced as a variable, not an array 
(e.g., Number) in the SUB statement. 


All arrays which are used within an external subroutine must appear in a DIM statement 
within the subroutine. Arrays which are passed-in are not DIM'ed in the same way 
as arrays which are purely local to the subroutine. Arrays which are local to a 
subroutine must be DIM'ed normally: the maximum length of each dimension of the 
array must appear within the array parens within the DIM statement: 


DIM LOCAL(10),LOCAL2(15,3), LOCAL$(100),LOCAL3$(7,250) 
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Arrays which hold passed-in values (that is, arrays which have accepted values from 
a "higher" routine) must be DIM'ed to show the number of dimensions they contain 
(single or double dimensioned arrays) but need not be DIM'ed accurately as to the 
length of each dimension: 


DIM Numbers(1,1),Passed$(1),Double$(1),Array(1),Terms$(1,1) 
Arrays with passed-in values are DIM'ed to identify them as arrays, ot to set their 


maximum size. Their size is determined by the pass, not by the DIM statement. The 
DIM statement must be accurate in the number of dimensions in the array (whether 


a given array is singly or doubly dimensioned) but need not be accurate in the length 


of each dimension. 
Example: 


Dim A(10,10),B$(100) 


Call Alter(A,B$) 


End 

SUB Alter(alpha,beta$) 

Dim alpha(1,1),beta$(1) 

Dim gamma(10,10),delta$(100) 
For outer=1 to 2 

counter=0 

For index=1 to 10 

For jindex=1 to 10 

On outer gosub 1,2 


Rem set array sizes 
Rem initialize arrays, other code here 


Rem call subroutine to reverse order of arrays 
Rem other code here 


Rem begin subroutine 
Rem dummy dimensioning of passed-in arrays 
Rem non-passed arrays dimensioned accurately 
Rem open outer loop. 

Rem initialize counter 

Rem open middle loop 

Rem open inner loop | 

Rem gosub extended range ia and replace) 


next jindex Rem close inner loop 
next index Rem close middle loop | 
next outer Rem close outer loop 
beta$=delta$ Rem string arrays can be rereneines as a whole 
Exit Rem back to main routine | 
Rem extended ranges are next; first to swap 
1 gamma(index, jindex)=alpha(11-index,11-jindex) 


Rem reverses values into gamma 


counter=counter+1 Rem count from 1 to 100 
delta$(counter;1)=beta$(101-counter;1) | 
Rem reverse values into delta$ 
return Rem back to loop 
Rem second extended range next: replace 
2 alpha(index, jindex)=gam ma(index, jindex) | 
Rem put reversed order in alpha 
return Rem back to loop 
End Rem end of subroutine 


2.7.4 CALL, SUB, FUN, EXIT Statements ; LANGUAGE 


This example reverses the order of the elements of two arrays, one numeric (A, called 
alpha in subroutine) and one string (B$, called beta$ in subroutine). Because the values 
of A and B$ are passed to the subroutine Alter, the arrays alpha and beta$ have 
dummy dimensions in their DIM statement. The arrays gamma and delta$, however, 
are entirely internal to the subroutine and must be dimensioned accurately in their 
DIM statement. On the first pass through the triple loop, the values of alpha and 
beta$ are reversed and inserted in gamma and delta$, respectively. On the second 
pass through the loops, the values of gamma are inserted in alpha, completing the 
reversal of elements in that array. Since the string arrays, unlike the numeric arrays, 
can be referenced as a whole, the reversed elements in delta$ can be inserted in beta$ 
in a single line. 


Subroutines headed by SUB statements are independent of and separate from the main 
routines which Call them. The subroutines which will be Called by a main routine 
must be compiled with the main routine (because only one file can be Loaded and 
Run) but can be listed in any order, before or after or surrounding the main routine. 
Variable and array names within a subroutine are independent of other routines (with 
the exception of the parameter/argument list value pass discussed above), as are line 
labels. 


Example: 
SUB S.One(A,B,C$) '‘ begin first subroutine 
DIM C$(1) ‘dummy Dim for passed-in $ 
On A/9.375 gosub One,Two,Three Else gosub Three! switch dictates action 
Exit ‘back to main routine 
One: C$=C$*(B-1) | first action line 
return ‘back to exit 
Two: C$=C$*(B-2) ‘second action line 
return | back to exit 
Three: C$=C$*(B-3) third action line 
return | back to exit 
End ‘end subroutine 
Rem Main program begins here ' begin main program 
. ' other code here 
One: Call S.One(A,B,C$) ' first Call 
Two: Call S.Two(A,B,C$) ‘second Call 
Three: Call S.Three(A,B,C$) ‘third Call 
| other code here 
End ‘end main routine 
SUB S.Two(A,B,C$) ' begin second subroutine 


2-70 


LANGUAGE 


DIM C$(1) 
If A LE B then 
For index=1 to A 
B=B+tindex 
next index 
Else 
A=B-1/A 
Endif 
C$=C$+B 
Exit 
End 
SUB S.Three(A,B,C$) 
DIM C$(1) 
For index=1 to A 
On index gosub One,Two,Three,Two,One 
next index 
Exit 

One: C$=C$&Bt1 
return 

Two: B=BtA 
return 

Three: Gosub One 
Gosub Two 
Gosub One 
return 
End 


2.7.4 CALL, SUB, FUN, EXIT Statements 


idummy Dim for passed-in $ 
‘compare A to B 
open loop 

‘add integer summation of A to B 
'close loop 
tif A GT Bia 
ichange A 
'end of comparison switch 
‘adjust C$ value 
iback to main routine 
‘end of subroutine 
ibegin third subroutine 
idummy DIM for passed-in $ 
iopen loop 
ion loop counter, go... 
iclose loop 
'back to main routine 
adjust value of C$ 
iback to loop 
‘adjust value of B 
iback to loop 
ichange C$ and come back 
ichange B and come back 
ichange C$ again & return 
iback to loop | 

iend of subroutine & program 


In this example, a variety of calculations are performed in three subroutines. The 
same variable and array names are used throughout, as are the three line labels One, 
Two and Three. This is allowable because the subroutines are separate frames of 


reference from the main routine and each other. 


If constants are used in a subroutine-CALL, the variables which accept the constants! 


values must not be assigned new values within the subroutine. 


Invalid example: 


Call Adder(1.14," plus ",2.45," equals") 


END 
SUB Adder(a,b$,c,d$) 
DIM b$(1),d$(1) 


PRINT a,b$,c,d$,ate 


Pis a=2.034 

P2 c=7.0879 
PRINT a,b$,c,d$,a+e 
Exit 
End 


1 . 
1eall subroutine 


‘end main routine 
‘begin subroutine 
idummy Dim's of passed-in 
‘arrays 

iprint line on video | 

ifirst problem line | 
‘second problem line 
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In the invalid example, the two lines P1 and P2, called first and second problem lines 


in the remarks, assign new values to variables which received constants' values in the 
SUB statement. The effect of these value reassignments is to endanger the values of 
the constants in the CALL statement when the subroutine EXIT's. 


Reassignment of values in this way is not legal. Results from any use of this procedure 
will be unpredictable: in most cases, system safeguards will prevent ill effects, but 
certain instances may produce fatal run-time errors, or even false values. 


definition: | EXIT statement 


EXIT 
EXIT expression 


An EXIT statement is either the reserved word EXIT alone, following a SUB statement, 
or the reserved word EXIT followed by an expression, following a FUN statement. 
The expression must be of the same data type as the name of the function in the 
FUN statement. 


When used with the SUB statement, EXIT statements send program control to the line 
following the CALL statement which invoked the subroutine and pass the argument 
list values back to the corresponding expressions in the main routine. 


When used with the FUN statement, the EXIT statement sends the value of the 
expression back to the use of the function name in the main routine (see FUN statement, 
below) in addition to returning passed-in values to the main routine and sending program 
control back to the invocation line. 


EXIT statements, in either form, pass values assigned to variables in the argument list 
back to the main program only if the expression used in the invocation parameter list 
was simple. In other words, complex expressions do not have their values replaced by 
returns from subroutines; simple expressions (consisting of a single element) do have 
their values replaced by returns from subroutines. 


Example: 


Call Crater(Apple,Orange*Pear,Peach$,Plum$&Prune$) 


End 

Sub Crater(a,b,e$,d$) 
Dim e$(1),d$(1) 
a=bt+2.654 

b=e$*5 

e$=b&d$ 

d$=b*a 

Exit 

End 
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| 
In this example, the value of the simple expression (numeric variable) Apple is assigned 
to the variable a; the complex expression Orange*Pear's value is assigned to the variable 
b; the simple expression (string array) Peach$'s value is assigned to the string array 
e$; and the value of the complex expression Plum$&Prune$ is assigned to the string 
array d$. Each of the subroutine variables and arrays has its value changed within 
the subroutine. The value of numeric variable a is passed back and becomes the new 
value of the numeric variable Apple; the value of the string array c$ is passed back 
and becomes the value of the string array Peach$. However, because b and d$ were 
given the value of complex expressions, their new values would not be jassigned to any 


part of the main program: their values would not be passed back but would be 
dis carded. 


The same rule applies to function subroutines. 
Example: 


‘other code here 


Subtotal(9,16)=Current+Sign(Delta-Daily$)*Delta invoke function Si 


° \other code here 
END ‘end main routine 
FUN Sign(Expression) 'begin function subroutine 
Sendback=0 ‘initialize holding variable 
If Expression LT 0 then fopen comparison test 
Sendback=-1 ‘value if Expression negative 
Else lif Expression GE 9... 
If Expression=0 Then 'open second comparison test 
Sendback=0 . value if Expression 
Else lif Expression GT 0... 
Sendback=1 value if Expression positive 
Endif fend inner IF-THE 
Endif 'end outer THEN 
Exit Sendback back to main routine 
End ‘End of subroutine and program 
In this example, the function Sign (which returns the sign of the argument, -1 if 
negative, 0 if 0, +1 if positive) is used to determine whether the amount of change 
Delta should be added or subtracted from the running total Current to give the day's 


record (which is recorded in the array reference Subtotal(9,16) ). Although the value 
of the variable Expression (which received the value of the complex expression 
Delta-Daily$) is not changed within the function subroutine, even if it had changed 
the value of Delta-Daily$ would not change, because values are not passed back to 
complex expressions. However, if Delta-Daily$ were replaced with a simple expression 
(Daily(9,16), for example) and if a value-changing line like the following were present 
in the subroutine: 


Expression=Sendback 
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Then the new value of Expression would be passed back to the main program and 
become the new value of Daily(9,16). 


definition: FUN statement 


FUN function name(argument list) 
definition: function name 


variable name 


alphabetic [up to 14 alphanumerics][$] 
definition: argument list 


variable name [variable namel|s, | | 


A FUN statement consists of the reserved word FUN followed by a function name 
followed by an argument list enclosed in parens. A function name is formed the same 
way as numeric and string variable names: an alphabet character optionally followed 
by up to 14 alphanumeric characters, followed by a dollar sign $ if it is string type. 
An argument list is the same as the argument list of a SUB statement: one or more 
variable names, separated by commas if more than one. 


Unlike CALL and SUB statements, the FUN statement argument list is required. At 
least one value must be passed through the argument list. In addition, data can be 
made available to FUN subroutines through the COMMON area (see Subsection 2.4.3). 


A FUN statement heads function subroutines. User-defined functions in STAR BASIC 
are written as subroutines but invoked as functions, by use within an expression in a 
statement in the calling routine. 


Example: 
‘ ;other code here 
A=Power(x,3)+1.0 ;funetion invoked 
‘ ;other code here 
END end main routine 


LANGUAGE 2.7.5 CALL CHAIN Statements 


FUN Power(base,exponent) | begin funetion routine 

Temp=1.0 | initialize holding variabl 

For i=1 to exponent 1 open action loop 
Temp=Temp*base | base*base*...*base exponent times 
Next i i close loop 

Exit Temp i back to main routine 

END 1 end function routine 


The function Power is invoked in the main routine in an assignment statement. The 
effect is to set the numeric variable A equal to one plus the value of| the cube of x. 
The value of x is passed to the variable base, the value of the constant 3 is passed 
to the variable exponent. Using a holding variable Temp and a loop, the value of x 
to the power of 3 (x cubed) is calculated. The Exit Temp line sends the value of 
Temp to be the value of Power(x,3) in the assignment line in the main program. The 
values of x and 3 are not changed but are also returned to the main program. Execution 
continues in the evaluation of the expression Power(x,3)+1.0, the assignment is executed 
and the main routine continues. 


Function subroutines differ from SUB subroutines in the method of invocation and in 
the value returned to the function name; other than those two differences, function 
subroutines are the same as SUB subroutines. 


Both SUB and FUN subroutines can be nested to a depth of 50. Care must be taken, 
however, not to re-invoke a SUB or FUN subroutine within the nests, since such 
reinvocations destroy the values passed and run a substantial danger of |endless looping 
as well. 


2eled CALL CHAIN Statements 


definition: CALL CHAIN statement 


CALL CHAIN(filename [,disk unit number | ) 


CALL CHAIN(string expression| numeric expression | ) 


A CALL CHAIN statement consists of the reserved words CALL CHAIN followed 
immediately by an open paren, a string expression, optionally by a| comma and a 
numerie expression, followed by a close paren. 


A CALL CHAIN statement invokes a new main program. The string expression 
designates the name of the object code program file which is to be loaded and run. 
The numeric expression, if used, designates which disk unit contains the new program 
(default is unit 0). 


A CALL CHAIN statement overlays the old program with a new program which is run 
from the beginning. Any files which are open remain open. 
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Unlike subroutine calls, values cannot be passed to the new program through the calling 
statement. Values can be passed to the new program by writing them into a file 
which the new program then reads, however, or through the COMMON statement (see 
Subsection 2.4.3). 


Examples: 
CALL CHAIN("PROGM1") 


CALL CHAIN("ARGPRG",1) 
CALL CHAIN(PROG$) 


invokes PROGM1 from disk unit 0 
invokes ARGPRG from disk unit 1 
invokes program whose name is 
contained in PROG$ from unit 0 
invokes program whose name is 
contained in P$ from unit designated 
by value of N+1 


CALL CHAIN(P$,N+1) 


2.8 ERROR HANDLING 


Errors in STAR BASIC programs fall into several categories. Compile-time errors 
(mistakes in statement syntax) are flagged during program compilation and a variety 
of specific messages are available to identify the specific type of error encountered. 
This type of error always generates automatic error handling, which cannot be disabled. 
See Appendix D for a discussion of compile-time errors. 


Run-time errors are errors encountered during program execution. Run-time errors 
fall into two categories: input/output (I/O) errors and non-I/O errors. Both types of 
run-time error handling can be disabled and program-controlled error handling substi- 
tuted. 


Automatie error handling of both types of run-time errors halts program execution and 
issues an error message on the video display in the following format: 


ERROR number AT location number 


where number is the error code number and location number is the approximate location 
in memory where the error occured. The meaning of each error code is given in 
Appendix D. The location number can be cross-referenced with the compiler listing 
to find where in the program the error occured. 


Certain arithmetic operations (division by zero, for instance) cause default values to 
be assigned as the result of the computation. The assignment of these default values 
does not result in a halt to the program nor is an error message issued. These default 
assignments are as follows: 
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Case Result 

+N/0 +.99999999999999E63 (Overflow) 

-N/0 -.99999999999999E63 (Overflow) 
0/0 +.99999999999999E63 (Overflow) 


Expression greater than 
+.99999999999999 E63 +.99999999999999E63 (Overflow) 


Expression less than 
-.99999999999999E63 -.99999999999999E63 (Overflow) 


Expression greater than 0 
but less than 1.0E-63 0.0 nderflow) 


Expression less than 0 
but greater than -1.0E-63 0.0 (Underflow) 


where +N is any positive, non-zero value and -N is any negative, non-zero value. 


Except for internal 1/0 (READ-DATA-RESTORE statements), all I/O errors can be 
handled (trapped) through a control group within each I/O statement's control list. See 
Subsection 2.10 and following for statement-by-statement discussion of the ERL and 
EOF control groups. 


In addition, both I/O and non-I/O errors can be trapped with an ON ERROR statement, 
which acts as a special type of conditional, executing a consequent) statement only 
when an error occurs. The use of ON ERROR statements is discussed in detail in 
Subsection 2.8.1 and following. 


The ERR and IOERR functions, which return the current error number and I/O error 
number, respectively, and the ERROR statement, which invokes an "artificial", desig- 
nated error condition, are frequently used in error handling routines. Their use is 
discussed in Subsection 2.8.2. 

The RESET ERROR statement disables a previously set ON ERROR statement and 
returns to automatic system error handling. Its use is discussed in Subsection 2.8.3. 


| ON ERROR Statements 


definition: ON ERROR statement 


ON ERROR executable statement 


a 


2.8.1 ON ERROR Statements LANGUAGE 


An ON ERROR statement consists of the reserved words ON ERROR followed by an 
executable statement. An executable statement is any statement except a declarative 
(COMMON, DIM, DATA, SUB, FUN or END), or a comment or a partial transfer 
statement (IF-THEN with no consequent, FOR, or NEXT). 


ON ERROR statements in effect are a special type of conditional: the consequent 
statement is executed only if (and when) an error occurs (an error which is not trapped 
by an I/O error control group). 
The commonest form of the ON ERROR statement is the form: 

ON ERROR GOTO statement label 
which directs program control to the line designated, usually the beginning of an error 
handling routine designed to deal with the errors expected in that section of the 
program. A frequently seen alternative form is this one: 

ON ERROR GOSUB statement label 
which allows at least a potential return to the line following the ON ERROR statement. 
Another form: 

ON ERROR ON variable GOTO statement label,statement label... 
can be used to trigger a variety of responses based on the value of the control variable. 
If the ERR function were used as the variable, the resulting multiple filter could be 
used to give a variety of responses based on the type of error encountered. 
Two other transfer statements can be used: 

ON ERROR CALL subname 

ON ERROR CALL CHAIN(filename) 
If a CALL statement invokes an external subroutine, the values of ERR and IOERR 
will be available to the subroutine. When (if) program control returns from the 
subroutine, it resumes at the line following the ON ERROR CALL... 
If a CALL CHAIN statement is used to invoke a new program after an error, all 


current values (including ERR and IOERR) are cleared before the new program is 
loaded and run. 
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LANGUAGE 


Example: 


hoa = > 


Wane 


NIndex: 


2.8.1 ON ERROR Statements 


SUB BoxRight/Code) 

Holder=0 

IF Code=2 THEN Holcer=16 

if Holder=0 then graphies will be normal 
if Holder=16 then graphics will be “linking 


ON ERROR PRINT CP$1,16),"Oonps, let's trv again" 
set error trap for entire print routine; simplv trv again 


FOR Index=1 TO 15 

PRINT CP$/60,Index),EL$ 
NEXT Index 
erase area which will get boxed 


FOR Index=1 TO 15 
ON Index GOTO 1,2,2,2,2,2,2,242425252525253 
1 is top of box 
PRINT CP$/60,Index),TLCorner$(Holder),HLine$/Holder), 
HLine$Holder), HLine$!Holder),TRCorner$/Hol¢e 
GOTO Nindex 
2 is sides of box 
PRINT CP$(60,Index),VLine$(Holder), 
CP$(64,Incex), VLine$(Holder\ 
GOTO Nindex 
3 is bottom of box 
PRINT CP$(60,Index),BLCorner$(Holder),HLine$/Holder), 
HLine$(Holder), HLine$(Holder),BR Corner$/Holder 
NEXT Index 
EXIT 
END 
FUN TLCorner$(Code) 
EXIT CHR$(128+Code) ° 
END 
FUN TRCorner$!Code) | top right corner 
EXIT CHR$(129+Code) 
END 
FUN HLine$!Coce) | horizorteal line 
EXIT CHR$(136+Code) 
END 
FUN VLine${Code) | vertieal line 
EXIT CHR$(137+Code) 
END 
FUN BLCorner$(Code) ; bottom left corner 
EXIT CHR$(120+Code) 
END 
FUN BRCorner$!Code) 
EXIT CHR$f131+Code\ 
END 


top left corner 


bottom right corner 
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128 is normal top left corner;144 is blinking 


i 


2.8.1 ON ERROR Statements LANGUAGE 


¥YYY: 


ON ERROR statements are only effective after they have been encountered 
in the program flow, although they are not executed until an error occurs. 
Also, once an ON ERROR statement has been triggered by an error, it 
is no longer active (unless it is reset by being encountered again in the 
program). 


ON ERROR traps are only effective within the local routine. If an ON 
ERROR trap is set in the main routine, it will not be effective during 
external subroutines. Likewise, an ON ERROR trap in an external 
subroutine is only effective within that subroutine. 


ON ERROR traps, once set by being encountered in program flow, are 
active until another ON ERROR statement is encountered, a RESET 
ERROR statement is encountered (see Subsection 2.8.3) or until the routine 
is held in abeyance (as by a subroutine CALL) or exited permanently (as 
by a CALL CHAIN statement), ON ERROR statements are not active 
during a subroutine CALL but are active once the subroutine exits and 
control returns to the calling routine. 


Example: 
El: ON ERROR GOTO Help 
CALL TSUB 


ON ERROR GOTO El 


CALL TSUB 
CALL RSUB 
CALL SSUB 


END 
SUB TSUB 


EXIT 

END 

SUB RSUB 

ON ERROR CALL SSUB 


EXIT 
END 
SUB SSUB 


LANGUAGE 2.8.2 ERROR Statement, ERR, IOERR Function Use 


E3: ON ERROR GOTO AAAA 
BBBB: . 

EXIT 

END 


In this example, several error traps and subroutines are used to illustrate ON ERROR 
activity. The ON ERROR statement at E1 sets an error trap which is active before 
and after the CALL TSUB statement just above XXXX, but the E1 error trap is not 
active during TSUB. An error at XXXX would be trapped by E1, but an error at 
YYYY would not. 


At E1.1, the trap at El is superceded by a new ON ERROR statement. An error 
between E1.1 and Help would send control back to E1, where El's ON ERROR statement 
would be reset and the code between El and E1.1 would be run again. 


TSUB does not contain an ON ERROR statement or other error handling so an error 
at YYYY would generate automatic system response. RSUB has an ON ERROR 
statement at E2, so an error at ZZZZ, for instance, would be handled by a CALL to 
SSUB, with control resuming at ZZZZ when SSUB EXIT's. 


SSUB has an error trap at E3. An error at AAAA would cause automatie system 
response, but an error at BBBB would be trapped. Since E3 calls for a GOTO AAAA, 
E3 would be reset before BBBB was encountered again. This type of trap could cause 
endless looping if an error at BBBB were not corrected at AAAA. 

2.8.2 ERROR Statement, ERR, IOERR Function Use 


definition: ERROR statement 


ERROR numeric expression 


The ERROR statement consists of the reserved word ERROR followed by a numeric 
expression. 


An ERROR statement invokes the error specified by the value, of the numerie expression 
(truncated to an integer if necessary). See Appendix D for run-time error codes. 


definition: ERR, IOERR functions 


ERR 


IOERR 


2.8.2 ERROR Statement, ERR, IOERR Function Use LANGUAGE 


The ERR and IOERR functions act as numeric variables whose current value is the 
last error and input-output (I/O) error code, zero if no error, or no I/O error, has 
occurred. ERR holds the code for all errors except I/O errors trapped by an error 
trap within the I/O statement itself (see Subsection 2.10 and following for information 
about the ERL control group). All I/O error codes are found in IOERR, whether they 
are trapped by the I/O statement's ERL group or by an ON ERROR statement. 


Care should be taken to preserve the value of ERR or IOERR in error handling. 
Another I/O operation, for instance, can destroy the value held in IOERR. 


Invalid example: 


ON ERROR GOTO ER.1 


XXXX REM error occurs here 


PRINT IOERR 


ER.1 


ee 


Assuming an I/O error occurs at XXXX, the initial error statement sends control to 
ER.1, where a PRINT statement is intended to display the value of the error. However, 
because PRINT itself is an I/O statement, IOERR gets reset to zero by the PRINT 
directive and the error code of the error at XXXX is lost. To accomplish the error 
code display, ER.1 should read: 


ER.1: IO=IOERR 
PRINT IO 


Because they are intrinsic functions, ERR and IOERR cannot be reset by an assignment 
statement (an attempt to assign a value to ERR or IOERR will cause an error). 


A common use (but not the only use) of the ERROR statement is in conjunction with 
ERR or IOERR, in an error filter. 


Example: Error Filter 
é | other code here 
Here: ON ERROR GOTO Help ;set error trap 
: | other code here 
XXXX ; error occurs here 
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: 1other code here 

Help: IF ERR=100 THEN GOTO Here ; check for subscript error 
ERROR ERR ‘if it's not 100, bust it 
END 


The Error Filter example tests the current error value in ERR to see if it is an error 
100 (subseript out of range). If it is, control passes back to the ON ERROR statement 
at Here, resetting the ON ERROR statement and continuing the program. (Presumably 
the subscript error is the result of a valid but erroneous input too large for the 
program, which would not be repeated. Otherwise, if a permanent error were present 
at XXXX, the program would loop until manually ended. 


Example: IOERR Filter 


IOE: ON ERROR GOTO IOTest ;set error trap 
‘ ;other code here 
XXXX ;error here 


other code here 


10Test: IF IOERR NE 0 THEN GOTO IOE iif it's an I/O error, go back 
ERROR ERR ‘if it's not an I/O error bust it 
END 


In this example, IOTest checks IOERR to see if an I/O error has occurred. If it has, 
control is sent back to IOE for another try at whatever I/O caused the error. If 
IOERR=0 (no I/O errors have occurred), then the ERROR ERR causes an automatic 
system response on the error number stored in ERR. 


Any number of numeric tests can be substituted for the single-value filters illustrated 
above. 


Example: Multiple Error Filter 


other code here 


E1: ON ERROR CALL MultiFilter iset error trap 


‘other code here 


2.8.2 ERROR Statement, ERR, IOERR Function Use LANGUAGE 


SUB MultiFilter error trap subroutine 
ON ERR GOTO 1,2,3,4,5,6,7,8,9,10, 
11,12,13,14,15,16,17,18,19,20, 
21,22,23,24,25,26,27,28,29,30, 
31,32,33,34,35,36,37,38,39,40, 
41,42,43,44,45,46,47,48,49,50, 
51,52,53,54,55,56,57,58,59,60, 
61,62,63,64,65,66,67,68,69,70, 
71,72,73,74,75,76,77,78,79,80, 
81,82,83,84,85,86,87,88,89,90, 
91,92,93,94,95,96,97,98,99,100, 
101,102,103,104,105,106,107,108,109,110 


> s+ > > > BD > PO 2 


1 

2 

3 ERROR ERR 

4 PRINT "DISK MEDIA ERROR, PLEASE CHECK DISKS AND RESTART" 
STOP 

5 PRINT "ERROR IN ATTEMPT TO READ DISKETTE DIRECTORY" 


PRINT "PLEASE CHECK DISKS AND RESTART" 
STOP 
«and SO On... 


This type of comprehensive error filter is not commonly used, since it largely duplicates 
the system responses available automatically. Many types of errors are not subject 
to program control if they occur (hard disk errors, for instance, normally require 
manual intervention to check the condition of the files on the disk and the disk media 
itself), While these errors can be trapped, there may be no error remedy available 
except to give a message to the operator and stop program execution. 


Multiple error filters, whether through the use of an ON...GOTO or a series of conditional 
statements, are useful in cases where a few of the common errors can be corrected 
and program flow continue. An error filter of this type is shown in the first example 
of Subsection 2.12.6, the sequential sort example. 


Error numbers 200 through 255 are reserved for programmer-defined (user-defined) 
errors. User-defined errors can be useful in simplifying coding if used appropriately 
although in many cases a simple GOTO would be preferable. 


Example: User-Defined Error 


El: ON ERROR GOTO ComeBackl 

Loop1: INPUT Hold$ 
IF Hold$(1;3)="END" THEN ERROR 201 
WRITE (LFN=RFile) Hold$ 
GOTO Loop1 

EndLoop1: 


other code here 
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o 


ComeBacki: . 

IF ERR=201 THEN CALL CHAIN("MAINMENU") 

IF ERR=16 THEN 
CALL RFileBackup 
PRINT CP$(1,16),"File problem, now solved; please input last item again" 
GOTO El 

ENDIF 

IF ERR GE 21 AND ERR LE 23 THEN 
CALL RFileCreate 
CALL Screen17 
PRINT CP$(1,16),"File problem, now solved, please start again:",CHR$(7) 
GOTO El 

ENDIF 

ERROR ERR 

END 


Since "END" is used as the routine-end command, the error trap around this input 
routine is used to catch "END" inputs through the use of a user-defined error, error 
201. This routine assumes that a screen display has been created to prompt the 
operator for correct input. An "END" input causes the conditional immediately after 
ComeBack1 to chain back to the main menu. The other tests after ComeBackl check 
for an end-of-file error (error 16) or for a file not open error (21 is file not open in 
write mode, 22 is LFN not open and 23 is record locked). Other errors are passed 
a to the automatic system response with an ERROR ERR statement. 


2.8.3 RESET ERROR Statements 


definition: RESET ERROR statement 
- RESET ERROR 
The RESET ERROR statement consists of the reserved words RESET ERROR. 


RESET ERROR statements are used to disable ON ERROR... traps, clear the value of 
the ERR function, and enable automatic system error handling. 


Example: 
Trap: ON ERROR GOTO ERROR.1 error trap set 
: other code here 
Reset: RESET ERROR error trap disabled, automatic 
system handling enabled | 
. 
c~ j program continues 


2.9 INTERNAL INPUT/OUTPUT LANGUAGE 
2.9.1 READ Statements 


In this example, an error trap is set at Trap, directing control to ERROR.1 (not shown) 
upon encountering an error. The error trap is active between Trap and Reset. When 
execution reaches Reset, the reset error statement disables the ON ERROR GOTO 
ERROR.1 statement and automatic system action will result from any subsequent 
errors. 


2.9 INTERNAL INPUT/OUTPUT 


Internal input/output is substantially different from other I/O types, the primary 
difference being that all operations are internal, making "input" and "output" somewhat 
misnomers. 


Internal I/O is conducted through the DATA, READ and RESTORE statements. DATA 
statements are programmer-inputs, lists of numeric and string constants intrinsic to 
the program. DATA statements are declarative statements and are discussed in 
Subsection 2.4.2. 


READ statements insert constants from DATA statements into lists of variables. READ 
statements' use in internal I/O is discussed in Subsection 2.9.1. (READ statements are 
also used in file 1/0; that usage is discussed in Subsection 2.12.1.) 


RESTORE statements are used to reset the DATA list to the beginning of a specific 
DATA statement. Their use is discussed in Subsection 2.9.2. 


2.9.1 READ Statements 


definition: READ statement 
READ variable list 


A READ statement (when used for internal I/O) consists of the reserved word READ 
followed by one or more variables separated by commas. 


A READ statement assigns the values of constants from the program's data list to the 
variable or variables contained within it. The first READ statement in the program 
begins at the first constant in the first DATA statement (see Subsection 2.4.2 DATA 
Statements). As each DATA statement's list is exhausted, reading continues on the 
next, until the program's data list is exhausted and an error condition results from 
additional READ tries, or a RESTORE statement is used to reposition the data pointer 
(see Subsection 2.9.2, below). 
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LANGUAGE 2.9.2. RESTORE Statements 


Example: 


Bright: DATA 5,"There was a young lady from Bright" 
DATA "Who traveled much faster than light." 
DATA "She departed one day" 
DATA "In a relative way" 
DATA "And came back the previous night." 


: . ‘other code here 


READ Lines 

FOR index=1 to Lines 
READ L$ 

PRINT L$ 

Next index 


In this example, the number of lines in the limrick is READ from the first DATA 
statement and inserted in the numeric variable Lines, which is used to set the number 
of iterations of the READ-PRINT loop. Each successive line of the limrick's text is 
then read into the string array L$, and displayed on the video. 

2.9.2 RESTORE Statements 


definition: RESTORE statement 


RESTORE statement label 


A RESTORE statement consists of the reserved word RESTORE, optionally followed 
by a statement label. 


A RESTORE statement resets the data pointer to the first constant of the data 
statement bearing the statement label. The statement label must be the label of a 
DATA statement. Without the optional statement label, the RESTORE statement resets 
the data pointer to the first constant of the first data statement in the local routine. 


Example: 


RESTORE Blake 
Loop: Read Stanza.length 
For index=1 to Stanza.length 
Read Pline$ 
Print Pline$ 
Next index 
;. ;other code here 
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DATA 4 
DATA "Tiger, tiger, burning bright","In the forests of the night" 
Data "What immortal hand or eye","Could frame thy fearful symmetry?" 


. | other code here 


Goback: RESTORE Bright 
Goto Loop 


In this example, the RESTORE Blake statement sets the data pointer at the DATA 
statement in the line labeled Blake. The line labeled Loop reads the number of lines 
from the DATA statement at Blake into the numeric variable Stanza.length, which is 
then used to set the number of iterations in the READ-PRINT loop. The four string 
constants are then successively READ into the string array Pline$ and displayed on 
the video. The second RESTORE statement, at Goback, assumes that the DATA 
statements used in the previous example are also part of this program. This RESTORE 
sets the data pointer at Bright, after which the Goto sends control back to the 
READ-PRINT loop which then displays the poem on the video. 


2.10 KEYBOARD, VIDEO, PRINTER INPUT/OUTPUT 


The video display, printer and keyboard provide the link between the operator and the 
F-85. Messages and displays on the video screen prompt data and control input from 
the keyboard for interactive control of the system, while longer term reports and 
statements are output on the system's integral printer, allowing distribution and 
permanent reference. 


INPUT statements accept input from the keyboard, inserting it into one or more 
variables for internal manipulation. Their use is discussed in Subsection 2.19.1. 


PRINT statements output on the video display. Their basie use is discussed in Subsection 
2.102% ‘ 


WRITE statements output on the printer. Their use in this mode is discussed in 
Subsection 2.10.3. (WRITE statements also output to disk files; this use is discussed 
in Subsection 2.12.2). 


Both PRINT and WRITE statements allow manipulation of data upon output, to create 
output of a predetermined form and order. The FORMAT option in the WRITE statement 
allows numeric data to be written in specified output formats. Its use is discussed in 
Subsection 2.10.4. In addition, the EDIT$ function can be used to convert numeric 
data to string form in specified formats. Its use is also discussed in Subsection 2.10.4. 


The display characteristics of both video and printer are controlled through the use 
of functions in the output expressions within the individual PRINT or WRITE statement. 
Printhead and paper position, cursor position, video screen display formats, and print 
font size and line length are all under software control. The use of these control 
functions is discussed in Subsection 2.10.5. 
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2.1051 INPUT Statements 


definition: INPUT statement 


INPUT [(input control list)] [variable list ] 
definition: input control list 


[ERL=statement label] [,PROMPT=string expression ] 


A [,CARR=numerie expression] [OPT=numeric ] 


An INPUT statement consists of the reserved work INPUT, optionally followed by a 
space followed by a control list in parens, followed by a space, followed by one or 
more variables, separated by commas if there are more than one. If there is no variable 
list entry, the INPUT statement waites for a carriage return. 


An input statement control list consists of one or more of these three control groups: 
PROMPT, CARR, or ERL. Each control group consists of the reserved word followed 
by the = sign followed by the appropriate label or expression. INPUT statements 
accept data from the keyboard and insert it into the variable(s) of the variable list 
(array references may also be used to receive data). The meanings of the control 
groups are as follows: 


PROMPT=string expression string expression's value is output on the video 
display as a prompt to the operator; 

CARR=numeric expression the cursor will advance n lines after the input is 
received (carriage return received from keyboard), 
where n is the value of the numeric expression 
truncated to integer; 

ERL=statement label execution transfers to the statement (the beginning 
of an error handling routine) if an error occurs 
during INPUT. 


OPT= numeric the options are bit-oriented and selection is by 

their sum. The options and values are: 

1l=do not echo input; 

2=do not filter input, pass values for arrow 
keys and control codes other than backspace 
RETURN, DEL and CAN; 

4=do not perform shift inversion on alphabetic 
characters. 


Example: "OPT=3" (1&2) could be used to input passwords 
without echoing them and the passwords could 
contain non-printing control codes no filter. 


REV. E 2-89 


2.10.1 INPUT Statements LANGUAGE 


The control's default values are as follows: 


PROMPT no prompt issued; 
CARR CARR=1; 
ERL automatic system error handling or on ON ERROR 


trap if one is active; 


Input from the keyboard must match the type and number of variables or array 
references in the variable list, in order through the list. If the variable or array 
reference is numeric, at least one numeric character must be first in the input or an 
error will result (the number of the error would be found in the IOERR function). 


INPUT statements accept a maximum of 80 characters from the keyboard. If more 
than 80 characters are to be input, either several INPUT statements should be used 
or a KEYIN$ routine (see page 2-105) written to accept the input. 


Numeric input will accept 14 significant digits, truncating any after the 14th. Numeric 
input will accept up to 20 characters as follows: 


optional initial sign 

up to 14 digits 
decimal point 

exponent indicator E 
exponent sign 

up to 2 exponent digits 


Numerie input terminates upon encountering a non-numeric character (that is, input 
halts at the preceding character upon encounter of a character not a digit or a decimal 
point or a sign or an E followed by a valid exponent expression). If a series of numeric 
variables are to be filled, the operator's input should use one or more blanks (spaces) 
to separate one value from another. A comma or other non-numeric separator could 
be used, but a single character string variable would be necessary between numeric 
variables on the variable list to accept the comma, or an error would result. 


If a string variable or string array reference is used, any STAR BASIC characters will 
be accepted from the keyboard. Input will be terminated on a RETURN. 


If an array reference is used, any substring references must obey the normal subscript 
rules; i.e., if INPUT A$(7;10) is used, A$ must have a current length of at least 16. 


If several string references are used in the variable list, the second (and successive) 
reference will receive input only if the first is filled. If a RETURN is encountered 
before the first string variable or array reference is filled, subsequent variables or 
array references will be nulled if string, zeroed if numeric. 


2-90 REV. E 


Y 


0 


LANGUAGE 2.10.2 PRINT Statements 


Examples: 
INPUT D$ no prompt, input accepted up to length of D$ 
INPUT (ERL=HELP)F no prompt, HELP is error line, numeric 
input into variable F accepted 
INPUT (PROMPT=A$)R$ value of A$ is prompt, R$ accepts string data 


2.10.2 


INPUT (PROMPT="Name of employee?")Name$ 
prompt is Name of employee? 
data inserted in Name$ 

INPUT (ERL=Input2,PROMPT="Number of items? "Items 
prompt is Number of items? 
error line is Input2 
data inserted in numeric variable Items 

INPUT Nuts,Bolts,Nails(1,5),Code$ 
no prompt or error line (prompt is presumablv 
done with a previous PRINT statement) 
numeric data separated by blanks is input in 
variables Nuts and Bolts and into the array 
reference Nails(1,5); Code$ accepts final section 
of line (including blank or other separator if 
used after the Nails(1,5) invut) 

INPUT First.line$,Second.line$,Third.line$,Fourth.line$ 
no prompt or error line ‘prompt presumably 
done with previous PRINT statement) 
each string array reference must be dimensioned 
to fit desired input; input continues until each 
string array reference is filled or a RETURN 
is encountered. 

Input (PROMPT=D$,ERL=E1) D21,D22,D23,F$ 
prompt is contained in D$, error line is E1; 
series of three numeric variables is filled, 
then a string reference 

Input (PROMPT=A$,CARR=0) IN$ 
prompt is contained in A$, no carriage return 
or linefeed are performed at end of input 

Input (PROMPT="Name?"&CR$&LF$,CARR=3) Name$ 
Name? output on video as prompt, CR$&LF$ 
causes input echoing to start at left end of 
following line, CARR=3 causes jump of 3 lines 
after input ends. 


PRINT Statements 


definition: PRINT statement 


PRINT [ (print control list)] expression list 


2.10.2 PRINT Statements LANGUAGE 


definition: print control list 
[ERL=statement label ][,CARR=numeric expression] 


A PRINT statement consists of the reserved word PRINT followed by a space, followed 
optionally by a control list enclosed in parens followed by a space, followed by one 
or more numeric or string expressions, separated by commas if there are more than 
one. 


A control list in a print statement consists of either the reserved word ERL (error 
line) followed by an equals sign = followed by a statement label, or the reserved word 
CARR (carriage return) followed by an equals sign = followed by a numeric expression, 
or both ERL and CARR expressions, in either order, separated by a comma. Because 
parentheses are used to enclose control lists, the expression list may not begin with 
parentheses (the grouping operators) if a control list is not used (i.e., PRINT (X+Y)*Z 
is a syntax error). 


PRINT statements output on the video display. Each expression in the expression list 
is evaluated and converted to character form before output. 


If ERL is used in the control list, the statement label designates a line to receive 
control if an error occurs in this output. If CARR is used, the numeric expression 
designates the number of lines to be advanced between PRINT statements. Default 
values are as follows: 


ERL=automatie system handling; 
CARR=1 line advance. 


If CARR=0, the cursor will remain at the positon immediately following the last output 
character and new output begins display at that position. 


PRINT statements produce string data as found within the string, for printable charac- 
ters. Non-printable characters are normally supressed, although certain control 
characters if found within a string will change the screen's output format or printing 
font. Use of these characters is discussed below, in Subsection 2.10.5, since their use 
is somewhat in common with printer output through the WRITE statement. 


PRINT statements evaluate numeric expressions and convert the resulting value to a 
character string using the following rules: 


ly a leading blank will always precede the leftmost digit or symbol in a number 

2: if the value is negative, a - sign will precede the first symbol or digit; if the 
value is positive, no sign will appear 

33 if the value can be expressed in 14 significant digits, with a decimal point as an 
optional 15th character, it will be output in that form 

4: if the value can be expressed in 14 significant digits or less in 20 characters or 


less with zeros or a decimal point in non-significant places, it will be 
output in that form 

5: if the value cannot be output according to 3 or 4, above, then it will be 
output in exponential form: 


[- ] .numberE [- exponent 
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Examples: 
Value Output 
a: 2001.3 2001.3 
b: -76.89635 -76.89635 
@: 923.745 E-2 9.23745 
d: 7.035E24 -7035E25 
2.3546E-19 -23546E-18 
fs -LE-18 -0000000000000000001 
g: .1E19 .1E19 
h: -10000000003456001344 -1000000000345 


Examples a and b illustrate positive and negative signing. All examples are preceded 
by a blank in output. Example ¢ can be output in less than 14 significant digits, with 
a decimal point, so the exponential form is not used. Examples d, e and g require 
exponential form output, because more than 20 characters would be required otherwise. 
Example f can be output in exactly 20 characters, a decimal point, one significant 
digit and 18 place-holding zeros, so the exponential form is not required. Example h 
is truncated at 14 significant digits; trailing zeros are not required and are supressed. 


Numeric output can be modified to a desired format with the EDIT$ function. Because 
this function can also be used to format printer output, it is discussed in Subsection 
2.10.4, following the printer output discussion. 


Examples: 

PRINT "This is a test" | This is a test displayed 

PRINT A$,D$,Team ivalues of A$,D$ and numeric 
variable Team displayed; if 
imore than one line required, 
imore are used as needed; 
;advances one line after end 
‘of output 

PRINT (ERL=Error.1)F$ idisplays value of F$; 


iError.1 is error line 
iif needed; advances 1 line 
‘after F$ is displayed 

PRINT (CARR=3) D$,Ralph$ ‘values of D$ and Ralph$ 
:displayed, on as many 
isueeessive lines as needed; 
iadvances 3 lines after Ralph$ 
‘is output 

PRINT outputs blank line on video, 
‘advances one line 

PRINT (CARR=5,ERL=Targ) outputs blank line; 
‘advances 5 lines; Tara is 
‘error line 
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print (ERL=B3,CARR=2)R$,G12 | displays values of R$ and Ww 
| G12, on as many successive 
i lines as needed; B3 is error 
| line; advances 2 lines after 
| G12's value 


Tabs, cursor position control, sereen format changes and font changes are all controlled 
using special functions in the PRINT statement's expression list. These usages are 
discussed in Subsection 2.10.5. 

2.10.3 WRITE Statements 


definition: WRITE statement 


WRITE (write control list) [expression list] 


definition: write control list* 


LFN=numerie expression [,CARR=numeric expression] |, FORMAT=string expression ] 
A [ IOLIST=statement_label][,ERL=statement label ] 


VU 


A WRITE statement consists of the reserved word WRITE followed by a space, followed 
by a control list in parens, followed by a space, optionally followed by one or more 
expressions, separated by commas if there are more than one. 


A write control list* consists of the LFN control group optionally followed by one or 
more of the following control groups: CARR, FORMAT, IOLIST or ERL. A control 
group in each case consists of the reserved word followed by an = sign followed by 
the label or expression indicated. If more than one control group appears, the list is 
separated by commas. Control groups can appear in any order in a control list. Each 
may appear only once. 


WRITE statements are used to send output to the printer.* Each expression in the 
statement's expression list is evaluated and its value sent to the printer for hardcopy 
display. WRITE statements also output to the video display if LFN=255. 


Unlike PRINT statements, the control list is required in WRITE statements. The sytem 
treats the printer as logical file zero, so the minimum control list in printer output 
is: 

(LFN=0) 


rr 


* WRITE statements are also used in file 1/9, with an extended control list. This ( ) 
use is discussed in Subsection 2.12.2. 
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The four optional control groups act as follows: 


CARR=numerie expression carriage return: advances n lines, where n equals 
the truneated value of the numeric expression, 
after the expression list is printed; 


FORMAT=string expression output format: formats output according to the 
value of the string expression ‘see Subsection 
2.10.4); 

IOLIST=statement label input output list: takes the expression list from 


the designated IOLIST statement; if this group 
is used, the WRITE statement intrinsic expres- 
sion list need not be used; see also Subsection 
2.4.53 

ERL=statement label error line: sends control to the statement if an 
error occurs during the WRITE ‘a within-the- 
statement error trap, active onlv during execu- 
tion of this statement). 


Default values for the control groups are as follows: 


LFN NO logical file number specified ‘an error); 

ERL no error trap set (automatic system handling 
or an ON ERROR statement would handle any 
errors); 

FORMAT standard format output is one character per 
byte ASCII output; 

IOLIST intrinsie expression list required. 

CARR one linefeed and carriage return terminates 
output. 


Like PRINT statements, WRITE statements use special functions in the output exnvression 
list to control print position, tab'ing and other display features. Use of these functions 
is discussed in Subsection 2.10.5. 


Because the printer is treated in some respects as if it were a disk file, it must be 
opened before data can be written to it. That is, OPEN ‘LFN=0. must appear before 
any WRITE (LFN=0)... statements can be used or an I/O error will res"lt. See Suhsection 
2.11.2 for a full discussion of the OPEN statement. 


The OPEN statement merely prepares the printer for I/O. Printer characteristics are 


set at default values (see below) unless a control function is used to set other values 
(see Table 2-6 I/O Control Functions). 
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Printer default characteristics are: 


Font: large (10 characters per inch) 
Line length: 132 characters per line 

Line spacing: 6 lines per inch 

Page size: 66 lines per page 


Just as the printer must be OPEN'ed, it should be CLOSE'd after use. In single-user 
applications, it is common to open the printer in an early program and to leave it 
open until the application is finished for the day. In multi-user applications, the printer 
would normally be opened only as needed, and closed immediately after use, to let 
another program get access. (See Appendix C for a discussion of multi-user applications 
planning.) Like the OPEN statement, an attempt to CLOSE the printer when it is 
already closed is an error. See Subsection 2.11.3 for a discussion of the CLOSE 
statement. 


WRITE statements may also be used to display material on the video. Normally PRINT 
statements are used for this, but in cases where the printer is in use by another 
program in multi-tasking mode (see Subsection C.1) use of LFN=255 in the WRITE 
statement will send output to the video. The statement might look like this: 

N=0 
W1: WRITE (LFN=N,ERL=PBusy,IOLIST=List12) 


PBusy: N=255 
Goto W1 


Unlike other LFN's, the video (LFN=255) does not have to be OPEN'ed. This usage is 
included as a special case specifically designed to aid multi-tasking programs and 
program debugging. 


Examples: 
WRITE (LFN=0) A$,N,B$ ivalues of A$,N and B$ 
output on printer 
WRITE (LFN=0,ERL=ER1)Name$ ivalue of Name$ output 
ion printer; error line is ER1 
WRITE (FORMAT="99.99",LFN=0)Number ivalue of Number is output 


ion printer using designated 

iformat (see Subsection 2.10.4) 
WRITE (FORMAT="X(20)",LFN=0,ERL=ER2) Data$ 

value of Data$ is output on 

iprinter, using string format, 

:20 characters 

(see Subsection 2.10.4); 

‘error line is ER2 


WRITE (LFN=0,CARR=0) Message$ ithe value of Message$ is output 
ito the printer; no carriage 
ireturn/linefeed is performed after 
ithe line is output 
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WRITE (LFN=0,CARR=5) D$ ithe value of D$ is output on the 
iprinter; a carriage return and five 
ilinefeeds are performed after out- 
;put 


2.10.4. FORMAT, EDIT$ Usage 


The WRITE statement FORMAT control group allows a certain amount of control over 
the form of output data. The intrinsic function EDIT$ is of more general use in 
controlling data formats, in that it can be used in a wide variety of statements, not 
only in output statements (WRITE and PRINT) but also in internal calculation statements 
(LET, IF-THEN and so on). 


The usages in both cases are somewhat similar, although not identical. FORMAT is 
intended primarily as a file-data control, but it can be used to format both numeric 
and string data for printer output to a limited extent. 


The EDIT$ function formats numeric and string data in several useful ways, allowing 
insertion of monetary symbols, check-protect characters and other forms useful for 
business reports as well as allowing insertion of text materials for more generalized 
uses. 


2.10.4.1 FORMAT 


The FORMAT control group is used primarily for file I/O, to control the type of output 
and input in WRITE and READ statements. Use of FORMAT descriptors allows control 
of the amount of precision of numeric I/O, the number of characters in string I/O and 
the type of storage used with numeric I/O if internal or packed BCD (binary coded 
decimal) coding is specified. 


When used in file I/O, the FORMAT group allows substantial space savings. Because 
the amount of numeric precision and the number of string characters can be controlled 
by the FORMAT group, it can also be used in printer output as a formatter. However, 
the EDIT$ function is substantially more useful in output (or input) data control (see 
Subsection 2.10.4.2). 


A FORMAT control group as used in WRITE statement printer output 


WRITE (FORMAT=string expression,LFN=0) expression list 


is a string expression containing a set of FORMAT descriptors for each expression on 
the WRITE statement expression list. FORMAT descriptors are groups of characters 
as described in Table 2-4. 


Examples: 

Descriptor Value Output 
99.99 102.345 error 
99.99 87.675 87.67 
99.99 -34.65 error 
99.99 -4.678 -4.67 
99.99 .0789 .07 


99.99 -0045 -00 


2.10.4 FORMAT LANGUAGE 


XXXXX TESTX TESTX 
XXXXX TO 45 TO 45 
XXXXX TOOTHY TOOTH 
X(10) This is a test This is a 
X(10) abedefghijklmnopq abedefghij 
X(10) 12345.67890123456 12345.6789 


In the examples above, the value 102.345 fails because it is greater than the maximum 
allowed range (99.99). The value of -34.65 also fails, because the - sign would take 
up one of the two places to the left of the decimal point, leaving no room to output 
the value. 87.675 is truncated on the right to fit, as is -4.678. Note that -4.678 
uses one place to the left of the decimal point for the - sign. 


In the string examples, none fail because any output will be accepted. TESTX and 
TO 45 are output as is, since they use only 5 character positions, matching the five 
in the format descriptor. TOOTHY is truncated to TOOTH to match the five-character 
descriptor. X(10) allows only 10 characters; each of the values is truncated after the 
10th position to fit. Note that the value 12345.67890123456 is truncated to 12345.6789, 
using the decimal point to fill one character position. 


Any valid string expression can be used to hold the FORMAT descriptors. 
Examples: 


A: WRITE (LFN=0,FORMAT=N$&E$&F$&M$) Number, E1$,E2$,Number.2 

B: WRITE (LFN=0,FORMAT=Area*Height*Price&Overhead$) Month.Total,Code$ 
C: WRITE (LFN=0,FORMAT="999.99,"&D$&"99.99") Credit,Debit,Difference 

D: WRITE (LFN=0,FORMAT=Sales$&Com mission$&Salary$&Total.Pay$)Sales, 

Pn Commission,Salary,Total.Pay 


Examples A,B,C and D show Write statements using the FORMAT control group option 
with a variety of string expressions as FORMAT descriptors. A shows the concatenation 
of a set of string arrays containing descriptors (presumably each string but the last 
ends in a , or else the sets of strings interlock to form four descriptors separated by 
commas). B uses a complex expression which evaluates as a string, suggesting that 
Area*Height*Price must be a value represented by a set of 9's. C uses two string 
constants and a single string array to hold descriptors, allowing the Debit value format 
to be dynamically adjusted while the Credit and Difference formats remain constant. 
D links a string array to hold the descriptor to the individual numeric variable in an 
obvious fashion. 


LANGUAGE 


Type 


Numeric 


String 


Internal* 


Packed* 


Table 2-4, FORMAT Descriptors* 


Description and Function 


a string of 9's with an optional decimal 
point: numeric value will be converted 

to ASCII characters, one character for 

each 9 in descriptor; value out of range 
(e.g., format 99 for value 1234) is I/O error 


a string of X's, or an X(number) where 
number is the number of characters in the 


string field; one character is printed for 


each X (or, up to the number); data shorter 

than the string descriptor is blank-filled 

on the right; data longer than the descriptor 

is truncated; a string of unknown (arbitrary) 

length can be indicated with X(*), which will 
accept any length string presented; however, 

if X(*) is used, it must be the last descriptor 
in the FORMAT group. 


a string of I's; represents the internal numeric format 


of the STAR BASIC runtime system; the first I holds the 


sign of the value and its exponent; each additional I 
holds 2 digits; descriptor must have at least 2 I's, 
maximum of 8 I's. 


a string of P's, optionally including a decimal point; 
numeric data is output as a string of Binary Coded 
Decimal numbers, packed 2 per byte; each P holds 

one digit (so there are 2 P's per byte); if an odd 
number of P's is specified in a descriptor, a 0 is padded 
on the right (if the same descriptor is used to read it, 
the 0 is invisible); if the value is negative, the first P 
in the descriptor holds the sign (a hexidecimal F), while 
if the value is positive, no sign is output (if required by 
the descriptor, a zero may be output, as in 3 output 
through "PP.P": data stored would be 03 00); if the 
decimal point is used, it is not output, but does position 
the value on input (i.e., if 98.56 is output through 
descriptor PP.PP, 9856 is output, while if P.PPP is the 
descriptor on input, the value read will be 9.856); as with 
numeric formats, if the value output cannot be read into 
the descriptor supplied for input (if PP had been given 
as the input descriptor in the example above), then an 
I/O error results; if the data has not been written in P 
format, an attempt to read it through a P descriptor 
results in an I/O error. 


Example 


99.99 
99999 
9999999.9 
-999999 


XXXXX 
XXXXRKKKEX 
X(20) 

X(47) 

X(*) 


PPPP 

PP.PP 

P.PPP 
PPPPPPP.PP 
PPP.PPEP 


* Printer use: file I/O allows use of Internal or Packed descriptors, but printer I/O 
does not. Printer FORMAT descriptors must be Numeric or String or an I/O error 


will result. 
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2.10.4.2 EDIT$ Function Use Lg 


Definition: EDIT$ function 


EDIT$(numeric expression,string expression) 


The EDIT$ function consists of the reserved word EDIT$ followed by an open paren 
followed by a numeric expression followed by a comma followed by a string expression 
followed by a close paren. | 


The EDIT$ function converts the value of the numeric expression to a specific format 
specified by the string expression, which must contain an EDIT$ designator string 
formulated according to the rules listed in Table 2-5 EDIT$ Designators. 


The EDIT$ function ean be used in output statements (PRINT or WRITE) to format 
data for output. It can also be used in internal calculations (LET or IF-THEN statements, 
for instance) to format data before or after internal manipulation. 


Examples: 

Value Designator String Output 
5286.45 ZLLZV.99 5286.45 Lad 
463.897 ZZZZV.99 463.89 
34.65 ZZZZV.99 34.65 
-3.1 ZZZZV.99 3.10 
5286.45 9999V.99 5286.45 
463.897 9999V.99 0463.89 
34.65 9999V.99 0034.65 
-3.1 9999V.99 0003.10 
5286.45 ——-V.99 error 
463.897 —V.99 463.89 
34.65 ——-V.99 34.65 
-3.1 —V.99 -3.10 
5286.45 ++++V.99 error 
463.897 +4++4+V.99 +463.89 
34.65 ++++V.99 +34.65 
-3.1 ++4++V.99 -3.10 
5286.45 ZZZZV.99- 5286.45 
-3.1 ZZZZV.99- 3.10- 
5286.45 ZZZZV.99+ 5286.45+ 
-3.1 ZZZZV.99+ 3.10- 
5286.45 ¥*ZZZV.99 5286.45 
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463.897 ¥*ZZZV.99 *463.89 

34.65 *ZZZV.99 ** 34.65 

-3.1 *ZZZV.99 ***3.10 
5286.45 $$$$V.99 error 
463.897 $$$$V.99 $463.89 

34.65 $$$$V.99 $34.65 

-3.1 $$$$V.99 $3.10 
5286.45 ZZZZV.99 CREDIT 5286.45 CREDIT 
463.897 ZZZZV.99 DEBIT 463.89 DEBIT 
34.65 ZZZZV.99 DM 34.65 DM 
-3.1 ZZZZV.99 FL 3.10 FL 
5286.45 Z,ZZZV.99 5,286.45 
5286.45 Z.ZZZV,99 5.286,45 
463.897 Z,ZZZV.99 463.89 
463.897 Z.ZZZV,99 463,89 


In these examples, the first eight show the use of the Z and 9 formats, the Z giving 
blanks if zero to the left, the 9 filling with zeros. The next eight show the use of 
the leading - and + signs, the minus blank if positive, - if negative the + giving + if 
positive, - if negative. The two errors occur because one position must be reserved 
for the leading - or + sign or blank. The next four examples illustrate the use of the 
trailing - and + signs. The next four show the use of the check-protect * character, 
while the four after that show the use of the monetary symbol (which can be replaced 
by any other symbol not listed on the EDIT$ Designator table, yielding similar results). 
The * does not give an error when fully replaced by digits (since in that case the 
check-writing field is full and the * filling is unnecessary) but the $ does require one 
space for the $ symbol and does yield an error if input is too high. The next four 
examples illustrate the use of literals trailing a numeric field, while the final four 
show both American and European separator usages. 


To output in column as shown, a position control function would be used to position 
the descriptors, as shown in the center column, above. Output is right-justified within 
the descriptor. 


Example of EDIT$ use in write statement: 


X = 25 
Y = 147.97 
Y1 = 8967.58 


Y$ = "$$$,$$$V.99" 

WRITE (LFN=0) EDIT$(Y,Y$),EDIT$(Y1,Y$) 

WRITE (LFN=0) EDIT$(Y,"ZZZV.99),TAB$(20), EDIT$(X,"229") 
PRINT CP$(10,5), EDIT$(Y,"$$$$V.99") 
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Table 2-5, EDIT$ Designators 


Character Significance 

9 Holds a place for a digit, produces a 0 if no significant 
digit appears in output value in place it holds 

Z Holds place for a digit, blanks if no digit present and place is to the 
left of the decimal point; acts as a 9 otherwise 

V Indicates that the value is to be positioned with its decimal point 
at the V position; does not print cecimal point: if one is desired, it 
should immediately follow the V fe.g., ZZZV.99 American notation, or 
ZZZV,99 European notation) 

= Indicates negative values with a minus - sign, positive values with no 
sign; may be used leading or trailing for even in the middle, for special 
output coding) 

+ Indicates positive values with + sign, negative values with - sign; may be 
used leading or trailing (or even in the middle, if there's reason for it) 

. When used in the leftmost position of the template, causes output to be 
filled with the check protect * character on the left of the first 
significant digit 

XX Any two identical, non-blank characters, other than the ones above, at the 
left end of the descriptor will blank any lefthand, non-significant zeros, 
preceding the first significant digit with the first character of the pair. 
Single characters (other than those above) will be blanked if to the left 
of the first significant digit, inserted literally if to the right of the first 
digit. 

2.10.5 Video, Printer Control Functions 


STAR BASIC uses a set of functions to control the phvsical characteristics of video 
and printer output, such things as cursor and printhead position, when to print a new 
line, when to change printing fonts or screen display formats, and so on. 


These functions are of three types: video exclusive (used only with video display), 
printer exclusive (used only with printer output) and non-exclusive (used with both 
printer and video). The syntax and use of these functions are listed in Table 2-6 I/O 
Control Functions. Other codes and procedures are listed in Tables 2-7 through 2-11. 


Table 2-6 I/O Control Functions Page 2-103 
Table 2-7 Video Display Feature (CF$) Codes Page 2-104 
Table 2-8 ASCII CODE (Decimal) Page 2-106 
Table 2-9 Video Graphic Character (CHR$) Codes Page 2-107 
Table 2-10 Keyboard Codes Page 2-108 
Table 2-11 Video, Printer Font Characteristics Page 2-111 
Table 2-12 Printer Boldface (Overstrike) Procedure Page 2-112 
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Table 2-6, I/O Control Functions 


Syntax Operation 
Video Exclusive Functions 

CF$(number) Coded feature: change feature code to number 
(see Table 2-7 Video Display Feature (CF$) Codes) 

EL$ Erase line: erase video from cursor positon to end of line; 
eursor does not move 

ES$ Erase sereen: erase video from cursor positon to end of 


FS$ [(number)] 


PF$(page,spaces) 


CP$(X,Y) 


TAB$(number) 


BS$[ (number) ] 
CR$ [(number) ] 
LF$ [(number) ] 


FF$[(number) ] 


CS$[(number)] 


sereen; cursor does not move 


Forward space: move cursor forward number of spaces; 
default is 1 space 


Printer Exclusive Function 


Printer form: set page length to page (number of lines); 
set line spacing to spaces/48 inches for<0<spaces =127; 
set line spacing to -(spaces-128)/48 inches 

for 128 =spaces<=239;<240<=spaces =?55 prohibited 


Non-Exclusive Functions (Both Video and Printer) 


"Cursor" position: absolute horizontal and vertical tab to 
column X line Y 


Tab: absolute horizontal tab to column number 


Back space: move left on line number of spaces; 
default is 1 space 


Carriage return: produces number carriage returns (no line- 
feed); default is 1 carriage return 


Line feed: advances number of lines down pagefsereen); 
default is 1 line feed; (no carriage return) 


Form feed: advance to top of next page felear screen, home 
cursor to top left corner); number is number of pages 
advanced; default is one formfeed 


Character size: clear screen (move to top of next page’; 
optional number (default is 0) changes font size: 

0= no change (clear screen; formfeed on printer) 

1= large font ‘clear screen; no formfeed on printer) 

2= small font (clear screen; no formfeed on printer’ 


X, Y, number, lines and spaces in all cases above can be replaced with a numeric 


expression with a value in the proper range, which will be truncated to integer if 


necessary. 
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Table 2-7, Video Display Feature (CF$) Codes 


Code Features Code Features 
0 normal 8 underline 
1 | highlight 9 + underline,highlight 
2 blink 10 underline,blink 
3 + blink,highlight 11 + underline,blink,highlight 
4 reverse 12 . *underline,reverse 
5 + reverse,highlight 13 + *underline,reverse,highlight 
6 reverse,blink 14 *underline,reverse,blink 
4 + reverse,blink,highlight 15 + *underline,reverse,blink,highlight 


*underline, reverse codes are equivalent to the corresponding reverse codes (i.e., 
reverse masks underline) 


| highlight is half intensity on ADDS, double intensity on F-85. 


The CF$ function outputs a special control character to the video display. The screen 
is considered to be a single line from 1,1 to 64,16 (or 80,24), with the beginning of 
each line to the left of the end of the line above. When a control code is output, 
it appears as a blank on the screen and is effective to its right until another control 
code appears. 


When the screen is cleared, it is filled with CF$(0) control characters to limit feature 
code effects. Likewise, when new lines are scrolled onto the screen, they are initially 
filled with CF$(0) characters. While this limits the effects of other feature code 
characters, good programming practice requires a CF$(0) call to terminate the output 
string. In addition, the ADDS terminal requires a CF$(0) code to terminate each 
feature if video display on the terminal is to match the console display, since clearing 
the ADDS Regent 40 screen does not fill it with CF$(0) characters. Likewise, if 
cursor control or tab functions are used within the output string, the separate parts 
of the string should be treated independently as far as feature control is concerned. 


Examples: 


PRINT (CARR=0) CS$(1),CP$(10,5),CF$(6),Message$,CF$(0) 

PRINT (CARR=0) CP$(10,7),CF$(2),"Call key operator",CF$(0) 

Header $=CS$(1)& CP$(20,1)& CF$(1)& Customer.Name$&CF$(0)&CP$(1,3)& 
CF$(1)&"Monthly Activity For "&Month$&CF$(0) 

Print (CARR=0) Header$ 
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} ie 


| CHR$, ASC and KEYIN$ functions 


| Unlike the other I/O functions, these three functions do not necessarily control printer 
or video attributes (although CHR$ may be used for this purpose). Rather, CHR$, 
ASC and KEYIN$ are special purpose, I/O utility functions. 


CHR§(numeric expression) returns a single byte binary string, the binary value of 
which equals the integer value (truncated, if necessary) of the numeric 
expression. Values from 0-127 are equivalent to the ASCII codes 0 to 127; 
| those codes are shown, with the decimal value used in the CHR$ function, 
| in Table 2-8. Values from 128 to 255 inclusive (above the ASCII codes) are 
also available. The values from 129 to 138 and from 144 to 154 inclusive, 
when output to the video display, generate the F-85's video graphic character 
set; these codes and their graphic characters are listed in Table 2-9. In 
addition, while the keyboard generates ASCII codes for ASCII symbols, the 
few non-ASCII symbols (the arrow keys, in particular) use an extension of 
the ASCII set. Up arrow is 250; down arrow is 251; right arrow is 252; left 
arrow is 253. Thus, CHR$(250) could be used in an input comparison to test 

for the up arrow key's being depressed. 


ASC(string expression) returns the ASCII decimal code value of the first character 
value of the string expression. The ASC function, therefore, is the reverse 
of the CHR$ function. 


c™ KEYIN$ bypasses the normal INPUT controls and filters. When the KEYIN$ function 
is used in an expression, the function assumes the value of whatever character 
is in the keyboard buffer. If there is no character in the keyboard buffer, 
KEYIN$'s value is null. KEYIN$ can therefore be used to halt program 
action when any key on the keyboard is depressed, or to input single characters 
without requiring a carriage return. 


Examples: Comments 
CHR3$(0) ‘value is NULL 
CHR$(27) ‘value is ESC (escape) 
CHR$(81) ‘value is Q 
CHR$(N*Rtotal) ' value according to value of expression 
ASC("A") | value is 65 
ASC("!") ‘value is 33 
ASC(D$&R$+1) 'value according to value of expression 


IF KEYIN$="Y" THEN GOTO Yon39 _ | action determined by what is present 
;in keyboard buffer when statement 
| encountered 

Holder$=KEYIN$ 'value of Holder$ set by keyboard 
'buffer when statement is encountered 


Hold.1: If KEYIN$="" THEN GOTO Hold.1 {hold here until key is depressed 


a 
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Table 2-8, ASCII Code (Decimal) , | 


WZ 
Lit Oo | 1 | 21 al 6 | 7 lee 
| O | NUL|SOH| STX |ETX| EOT|ENQIACK|BEL [BS [| HT | 
i Oe ea - SO] SI | DLE|DC1 [DC2[DC3 | 
| 2 | DC4 
es 
ra ie 
aac 
The left column gives the most signifi- 
cant digit(s), the top row the least sig- 
nificant digit. (Thus, @ is 64, DEL is | 
127, ETX is 3.) 
Abbreviations: \ 
0 NUL Null 17 DC1 Direct control 1 | 
1 SOH Start of heading 18 DC2 Direct control 2 
2 STX Start Text 19 DC3 Direct control 3 
3 ETX End text 20 DC4 Direct control 4 
4 EOT End of transmission 21 NAK Negative acknowledge 
5 ENQ Enquiry 22 SYN Synchronous idle 
6 ACK Acknowledge 23 ETB End transmission block 
7 BEL Bell 24 CAN Cancel 
8 BS Backspace 25 EM End of medium 
9 HT Horizontal tab 26 SUB Substitute 
10 LF Linefeed 27 ESC Escape 
11 VT Vertical tab 28 FS Form separator 
12 FF Formfeed 29 GS Group separator 
13 CR Carriage return 30 RS Record separator 
14 sO Shift out 31 US Unit separator 
15 SI Shift in 32 SP Space 
16 DLE Data link escape 127. DEL Delete 
The ASCII code set ean be sent to the video display or printer bv using the CHR$ 
function in a PRINT or WRITE statement with the cecimal ASCII code number as the | 
function's argument: CHR$ code). The CHR$ function is modulo 256, so the possible 
range is 0 to 255, with the higher numbers repeating the 0 to 255 codes. Additional 
uses of the CHR$ function are found in Tables 2-9 and 2-10. 
ww 
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Table 2-9, Video Graphic Character (CHR$) Codes 


Normal Blink Name Character 
128 144 Top Left Corner [ 
129 145 Top Right Corner | 
130 146 Bottom Left Corner |. 
131 147 Bottom Right Corner | 
132 148 Top Intersection 7 
133 149 Right Intersection — | 
134 150 Left Intersection LL 
135 151 Bottom Intersection _ iL 
136 152 Horizontal Line — 
137 153 Vertical Line | 


138 154 Crossed Lines ps 


Codes 139 to 143 and 155 to 159 are illegal and should not be used. 


The F-85's video graphic character set can be generated by using the CHR$ function 
in PRINT statements with the code set at the desired graphic character. These codes 
are above (and in addition to) the ASCII character set described in Table 2-8. 
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in ss sae ilar ag 


Table 2-10, Keyboard Codes 
Key Normal _ Shift Code Remarks 


F-85 Standard Keyboard 


space 32 32 = 

ESC 27 27 Error 105 Code ESC is an automatic error 
105. 

TAB 9 9 Printer resume 

DEL 127 127 — 

CAN 24 24 126 

RETURN 13 13 _ 

Arrows 

Up 250 250 31 

Down 251 251 254 

Right 252 252 29 

Left 253 253 30 

A 97 65 1 

B 98 66 2 

Cc 99 67 3 

D 100 68 4 

E 101 69 5 

F 102 70 6 

G. 103 71 7 

H 104 "2 8 

I 105 73 9 

J 106 74 10 

K 107 75 11 

L 108 76 12 

M 109 77 13 

N 110 78 14 

O 111 79 15 

P 112 80 16 

Q 113 81 17 

R 114 82 18 

s 115 83 19 

T 116 84 20 

U a ba ye 85 21 

V 118 86 22 

Ww 119 87 23 

X 120 88 24 

Y 121 89 25 

Z 1:22 90 26 

0 48 41 _ Use Normal value for all keypad 
kevs 

1 49 33 Top of form 


on printer 
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Table 2-10, Keyboard Codes (cont'd.) 


Key Normal _ Shift 
2 50 64 
3 51 35 
4 52 36 
5 53 37 
6 54 94 
7 55 38 
8 56 42 
9 57 40 
- 45 95 
= 61 43 
[ 91 93 
\ 92 124 
; 59 58 
: 39 34 
44 60 
‘ 46 62 
/ 47 63 


ADDS Regent 40 


Code Remarks 


Set top of form 
on printer if STOP 
is down 

Print sereen 


31 45 only on keypad 


_ 44 onlv on kevpad 
_ 46 only on keypad 


Like the F-85, alphanumeric and numeric keys generate the normal ASCII code for 
their character(s). Keys which generate special codes are listed below. 


BREAK = -_ 
CONTROL — — 
DEL 95 127 
ENTER 13 13 
NEW LINE 13 13 
ERASE = - 


_ Generates a 509-millisecond spac- 
ing condition on the output line. 


_ When used with any alphanumeric 
key, sets the seventh bit of that 
key's ASCII code to zero (subtract 
64 from the decimal ASCII code’. 


— ERASE alone erases to the end of 
lines CONTROL SHIFT ERASE 
erases to end of page fend of 
sereen’; CONTROL ERASE clears 
sereen. 
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Table 2-10, Keyboard Codes (cont'd.) 


Key Normal Shift Code Remarks 

ESCAPE 27 27 _ 

LINE FEED 10 10 _ 

LOCAL = — on Enters or leaves LOCAL mode 


(data link maintained but all trans- 
fer stopped). 


SHIFT = = _ Toggles the sixth bit of the ASCII 
eode when used with an alpha- 
numeric key (adds or subtracts 32). 
SHIFT-ESCAPE causes an alpha- 
shift lock. 


HOME 1 1 _ 

Arrows: 

Up 26 26 = 

Down 10 10 _ 

Right 6 6 ont 

Left 21 21 = 

AUX = = = Enables or disables auxiliary port 


(if enabled, auxiliary port receives 
all data from the keyboard and 
the F-85, for logging or hard-copv 
echo, for instance). 


Special Function Keys: 


Fl 2 49 2 33 _ The special function keys all gen- 
F2 2 50 2 34 = erate two bytes, a STX followed 
F3 2 51 2 35 = by another character. 

F4 2 52 2 36 — 

F5 2 53 2 37 oes 

F6 2 54 2 38 

FT 2 55 2 39 _ 

F8 2 56 2 40 _ 
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Large 


Font: 

Line length: 
Line spacing: 
Page size: 


Small 


Font: 

Line length: 
Line spacing: 
Page size: 


Default: 


2.10.5 Video, Printer Control Functions 


Table 2-11, Video, Printer Font Characteristics 


Printer . 
CS$(1),PF$(66,8) 


10 characters/ineh 
132 characters/line 
6 lines/ineh 

66 lines/page 


CS$(2),PF$(66,8) 
16.5 characters/inch 
217 characters/line 
6 lines/inech 

66 lines/page 


Large 


To set font and form: 


Video 
CS$(1) 


7 x 9 dot matrix 
64 characters/line 
4 lines/inech 

16 lines/sereen 


CS$(2) 

5 x 7 dot matrix 
80 characters/line 
5 lines/ineh 

24 lines/sereen 


Large 


Printer: WRITE (LFN=0 [,ERL=statement label |) CS$(number),PF$(page,spaces) 


Video: PRINT CS$(number),CF$(number) 


where CS$ sets font, line length (and page size on video), PF$ sets page size 


and line spacing on printer, CF$ sets video display format (see Tables 2-6 and 2-7) 
Printer: WRITE (LFN=0[,ERL=statement label]) CHR$(27),CHR$(12),CHR$(0) 


sets top of form at current paper position. 


Note on the PF$ function: PF$(page,space) sets the number of lines per page to the 
value of the first parameter, page, and the spacing between lines as a function of the 
second parameter, space. Line spacing is set in 1/48th inch increments, as follows: 
for space between 0 and 127 inclusive, line spacing is set to space/48 inches per line; 
for space between 128 and 239 inclusive, line spacing is set to - pace-128)/48 inches 
per line; values of space between 240 and 255 inclusive are illegal; the function is 
modulo 256, so values above 255 or below 0 repeat the sequence above. For example, 
PF$(66,8) sets the normal page: 66 lines of 6 lines per inch. PF$(66,136) sets the 
reversed normal page: 66 lines, 6 lines per inch, line spacing reversed. If PF$ is 
used to set an unusual printer format, it should be used again to reset the printer to 
normal format before the printer is closed. Opening the printer sets the large font, 
normal page format, but closing the printer does not change the format. Thus, a new 
program opening and using the printer will get the normal format, but a console 
operator using CODE 3 to print a video screen after a program using an unusual format 
could get the unusual format (such as reverse line spacing). 
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Table 2-12, Printer Boldface (Overstrike) Procedure 


WRITE (LFN=0,CARR=0) expression, BS$(LEN(expression)),expression 


or 


WRITE (LFN=0,CARR=0) TAB$(Number),expression, TAB$(Number),expression 


The second alternative has the advantage that if more overstrikes are desired for an 
even darker boldface, addition of a statement label and a transfer statement allows 
as many iterations as desired. The first alternative has the advantage that knowledge 
of the print position is unnecessary: the line will produce a boldface expression wherever 
used. 


Example: 


The following is a long video display subroutine which accepts lines to be displayed 
as a single long string array, Message$. Other parameters passed in from the CALL 
statement are LineLENGTH, a numeric array whose individual references are the lengths 
of the substrings of Message$; NumLINES, a numeric variable containing the number 
of lines (substrings) contained in Message$; and IsItBoxed, a numeric variable which 
will enclose the display in a reverse video square if its value is 0. 


The subroutine is written in four major sections: The Title and Initialization Routine 
labels the program and the parameters and sets the values of two internal elements, 
a string variable VBOX$ (used in creating the vertical sides of the box) and a string 
array, BOX$ (used in creating the horizontal top and bottom of the box). 


The Input Error Check Routine examines the parameters to ensure that a display longer 
than the screen is not attempted. The length of each line and the number of lines 
(with allowable values adjusted according to whether or not a box is to be used) are 
tested before display is attempted. The subroutine is aborted if input displavs fail 
these tests. 


The Box Routine uses IsItBoxed to direct its action. BOX$ and VBOX$ are used if a 
box (square in lines 1 and 15, columns 1 and 64) is to be displayed. If no box is 
specified, control passes to the Print Routine. 


The Print Routine displays the input lines, breaking apart Message$ into its component 
lines (substrings), centering each line horizontally, centering the group of lines vertically 
on the video screen. 


TITLE statements are used to separate the subroutine into pages, by routines, in the 
compile-time listing. 
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Video Display Subroutine/Input Error Check Routine 


TITLE 


"VIDEO DISPLAY SUBROUTINE" 


SUB VDisplay (Message$,LineLength -NumLines,IsItBoxed) 


THIS SUBROUTINE GENERATES VIDEO DISPLAYS 


Argument Type 


Messages string array 


LineLength numeric array 
numeric variable 
IsItBoxed numeric variable 


Numlines 


1} INITIALIZE: 


‘END 
TITLE 


Dim Message$(1)>-LineLength (1) 
Dim Box$(64) fixed, VEoxt(2) 


VBox$=CF$(4)&" " 
Box$=VBox$ 


Print (CARR=0) CS#(1) 


INITIALIZATION 
"YDisplay INPUT ERROR 


IF IsItBoxed=@ then 
If NumLines GT 13 then 


LTest=56 


ELSE 
If NumLines GT 15 then 


LTest=64 
ENDIF 


For Check=1 to NumLines 


Use 


contains print lines 
length of each line 


total number of lines 


box flag 


idumay dims mark arrays 
ire@al dim, local arrays 


ireverse video & blank 
‘fill: reverse blanks 


‘clear screen 


CHECK ROUTINE" 


ibox display 


goto ErrorMessagel 


itoo big for box 
imax line length 


idon’t box display 


goto ErrorMessagel 


ites big for screen 
‘max line length 


‘test each line langth 


Tf LineLength(Check) GT LTest then goto ErrormMessage2 


Next Check 
Goto DTheckEnd 


ErrormMessagel: 


iline is too long 


ut 


hit @rcor messages 
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Print "Too many lines in this display" 
EXIT ikill with message 


ErrorMessagec: 
Print "Line", Check," too long for screen" 
EXIT ikill with message 


CheckEnd: iit checks, display it 


TITLE "VDisplay BOX ROUTINE" 


If IsItBoxed=0 then ibox display: 
Print (CARR=0) CP$(1,1) -Boxt itop line 
Print (CARR=0) CP$(1,15) ,-Box$ ibottom line 
For Index=2 to 14 ivertical lines 

Print (CARR=0) CP#(1,Index) »,VBox$, 
. CP$(63,Index) ,VEoxt 

Next Index 

Endif 


TITLE "“VDisplay PRINT ROUTINE" 


VStart=(16-NumLines) /2 iset top of screen 
For. Y=1 to NumLines 
If Y=1 then iset string pointer 
Start=1 
Else 
Start=Start+LineLength (Y~1) 
Endif , 
X=32-LineLength (Y) /2 ‘center line 
Print (CARR=@) CP$(X,Y+VStart) - 
* Messages (StartiLineLength(Y))- 
Next Y 


EXIT 
END 
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This is CHRS.DEM. 
It illustrates the ASCII character set 
and the CHRS function. 


Firet, choose video or printer output? 


INPUT (CARR=@,Prompt=CS$(1)&CPS(5,5)&"Video or printer?"®& 
CP$(5,6)&"V=Video, P=Printer ") Tests 

If Test$="V" then goto Video 

If Test$="P" then goto Printer 


Print (CARR=9) CHRE(7) iding bell 
Goto Top 
Video: 
For I=@ to 255 ido all 254 
Print 1,FS%(5) ,CHR#(T) inumber, character 
Next I 


Input (Prompt="Again? ") Tests 
If Test#="Y" tnen goto Top 
STOP 


Printer: 


OPEN (LFN=@) iopen printer 
For I=@ to Z55 
WRITE (LFN=®) 1,Tab%#(5) -CHRS(T) iprint number -character 
Next I 
CLOSE (LFN=0) iclose printer 
Input (Prompt="Again? ") Tests 
Tf Tast$="¥" then goto Top 
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The example program CHR$.DEM displays the ASCII character set ‘and beyond, to the 
255 limit of the CHR$ function) on either the video display or the printer. The 
program is broken into three sections, the initial title and video/printer display choice 
routine, the video display routine and the printer routine. Each of the display routines 
displays the results of sending values 0 to 255 to its respective output device, with 
the value being sent at the left the CHR$ character on the right. 


When the CHR$ function values are output to the video display, visible character 
output starts at 33 (the ! character) and continues through the ASCII character set to 
126. The (beep) audible signal at value 7 is the BELL character, making the keyboard 
bell (actually more of a buzz than a bell) sound. Following the line deletion at 127, 
the video graphics set is displayed. The screen format codes lie between 224 and 239. 
Illegal codes 139-143, 155-223 and 240-255 cause blanking and other erratic effects. 


When the character set is output to the printer, several linefeed and page eject control 
effects are visible at values below 32. 32 is the first printable character ‘as in the 
video) but like the video screen, the printer does not make a blank space visible in 
normal printing operations. Value 33 gives the ! and the printable ASCII set continues 
through 127, where the delete character receives a printable symbol. Action beyond 


127 is somewhat erratic, as some characters trigger control codes, but no graphic set 
is available on the printer. 


At the end of each output routine, the CHR$.DEM program then asks if another display 
is desired, or if the opposite type of display is desired, before going to termination. 


Example: 


TOP:CALL BIGBOX 
HOLD: IF KEYIN$="" THEN GOTO HOLD 


GOTO TOP 
END 
SUB BIGBOX 
RRINT (CARR=0) CS#(1) ‘clear screen 


iprint horizontals 
FOR I=2 TO 63 
PRINT (CARR=@) CP$(I,1) ,-CHR$(136) ,CP$(I,15) ,CHR$(136) 
NEXT I 


iprint corners 

PRINT (CARR=@) 
CP#( 1, 1) -CHRS(128), 
CP$(64, 1) -CHR#(129) ; 
CP$( 1,15) ,CHRS(130) -» 
CP$ (64,15) ,-CHRS(131) 


> > > > 


iprint verticals 
FOR I=2 TO 14 
PRINT (CARR=0) CPS(1,/1) »CHR$(137) ,CP$(64,1) -CHRS(137) 
NEXT I 


EXIT 
END 
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In this example, the video graphic set is used to create a large square around the 
outside of the screen. Unlike the reverse video box of the earlier example, the graphic 
characters form a single line, continuous square. 


The other graphic characters (see Table 2-7) allow creation of multiple boxes, linked 
in a variety of ways, as well as use of blinking graphics. 


While this example is written as a subroutine, it could also be written as a function. 
If that were done, rather than a set of print statements, the CHR$ function would be 
used to construct a print-string, which would then be returned to the function call as 
the value of the function (which would be used in PRINT statements just as the control 
functions are used). 


The example P.EXAMP shows the basic use of the printer in a simple report format. 
The data in this case is contained in internal I/O, for easy visibility, but actual 
operations would normally involve reading disk-stored data from disk files. 


Note that the printer must be opened before use, just like a disk file. The WRITE 
statements immediately following the OPEN (LFN=0) statement set font size, perform 
a page eject to move to the beginning of a new page, and perform 2 linefeeds to 
position the page header. 


The assignment statement TEMP=45-LEN(LINE$)/2 set the TAB's in the following WRITE 
statement to center the header over the column headers. The double TAB$(TEMP),LINE$ 
phrase in the WRITE statement causes the header (contained in LINE$) to be printed 
twice in the same place, producing a boldface line. 


The column headers are simply printed at the 10,20,30... column positions, since all 
data is string and is printed flush-left beneath the column headers. 


The example illustrates a development stage, since 8 column headers are listed, but 


only 5 are used. The three Jump labels in the string-breaking ON GOSUB would be 
filled as additional data fields are added to the program. 
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' THIS IS P.EXAMP 
Dim Line#$(132) 
Dim Scratch$ (132) 
Head:Data "This is the report heading” 


tholds each line 
iscratch space 


Col: Data "Column 1","Column 2","Column 3","Column 4" 
Data "Column 5","Column 6","Column 7","Column 8" 


Info:Data 

® "Name 1,Ad 1,City 1,S1,ZIPO1" 
- "Name 2,Ad 2,City 2,S2,ZIPQ2" 
" "Name 3,Ad 3,City 3,53,ZIP03" 
* "Name 4,Ad 4,City 4,S4,ZIPQ4" 


"Name 6,Ad 6,City 6,S6,ZIPQ6" 
"Name 7,Ad 7» City 7 »S7,ZIPO7" 
"Name 8,Ad 8,City 8,S8,ZIPQ8" 
"Name 9,Ad 9,City 9,59,ZIP09" 
"Namel@,Ad1@,City19,10,ZIP10" 
OPEN (LFN=0) 

WRITE (LFN=@) CS#(1) ,PF%(66,8) 
WRITE (LFN=@) FFS,LFS(2) 
Restore Head 

Read Lines 

Temp=45-LEN (Line) /2 


, 
’ 
"Name 5,Ad 5,City 5,S5,ZIP@5", 


fopen printer 

tset font, page 
inew page, 2 lines 
{set data pointer 
tread header 
‘centers line 


WRITE (LFN=0) Tab$(Temp) ,-Line$,Tab$ (Temp) ,Line$ 


Restore Col 
For I=1 to 8 
Read Lines 


twrite header in 
tboldface 

iset data pointer 
18 columns 

tread column header 


Write (LFN=0,CARR=0) Tab$(I#10),Line$ !write col header 


Next I 
WRITE (LFN=0) 
Restore Info 
ON ERROR GOTO Jump 
For I=1 to 10 
Read Lines 
For J=1 to 8 


tnext line 

'set data pointer 
itrap for data over 
110 data "records" 
tread "record" 
ibreak into fields 


On J gosub Name-Ad-Cit,St,ZIP,Jump,Jump -Jump 


‘go get field 


Write (LFN=0,CARR=@) Tab#(J#10) ,Scratchs 


Jump! Next J 
WRITE (LFN=0) 
Next I 
Write (LFN=@) FFS 
CLOSE (LFN=®0) 
STOP 


Name! Scratcht=Lines$ (136) 
Return 

Ad: Scratch#=Lines(8;4) 
Return 

Cit: Scratch#=Line$ (1376) 
Return 

St: Scratch$=Line$ (2072) 
Return 

ZIP: Scratch$=Lines$ (2375) 
Return 
END 
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tand write it in col 
inew line 
Ipage feed. 


tclose printer 
tquit 
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2.11 FILE CREATION, FILE EXTERNALS 


A file is a set of records on a diskette. Input/output operations to files are carried 
out with a set of general purpose directives which work with the three types of files 
supported by STAR BASIC: sequential, random access (also called relative record) and 
Indexed Sequential Access Method (ISAM) files. 


File I/O directives are of two general types, those which work with the "outside" of 
a file, that is, with a file as a whole, and those which work the "inside" of the file, 
the records the file contains. 


The external file directives are ALLOCATE (file creation), OPEN, CLOSE, RENAME 
and DATE. The statements these form are treated in this subsection. The internal 
file directives are READ, WRITE, DELETE, UNLOCK and REWIND. The statements 
these form, for manipulation of file records, are discussed in Subsection 2.12. 


Sequential Data Files 


Sequential data files contain variable length records. The first byte of each record 
contains the record length count. This type of file is normally used for text files, 
passive storage of data which is to be output in a large batch on an occasional basis. 


Random Access (Relative Record) Data Files 


Random access data files have records of a single, fixed length. Because each record 
is a set length, any desired record can be read at any time, by record number. This 
type of file is most often used for on-line data storage, where access will be frequent, 
but its utility is overshadowed by the advantages of ISAM. 


ISAM Data Files 


ISAM files consist of two files: an index file and a master data file. The index file 
holds keys sorted in ASCII collation order, which are used to access individual records 
from the master data file. Cross-reference ISAM files, using the key of the first 
ISAM file as part of the new key, effectively allow quick sorts of information by any 
part of the record on a spot basis or as a continuing cross-reference procedure. Access 
by partial keys is also a relatively simple procedure. 


STAR BASIC uses the same statements, with varying parameter lists, to create and 
manipulate all three types of files. 


ALLOCATE statements create files, reserving space on the diskette and adding the 
file name to the disk directory. ALLOCATE statements, including a discussion of 
ealeulation of file size, are discussed in Subsection 2.11.1. 


OPEN statements ready files for use, assigning a logical file number (LFN) to each 
open file. OPEN statements are discussed in Subsection 2.11.2. 
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CLOSE statements end use of a file, freeing its LFN for use on another file. Optionally, 
CLOSE statements may truncate the unused space from the end of a sequential file, 
or delete a file altogether. CLOSE statements are discussed in Subsection 2.11.3. 


RENAME statements change the name of a file. Their use is discussed in Subsection 
2.11.4. 


DATE statements add a date to the directory listing of a file, usually signifying the 
last date of use of the file. DATE statements are discussed in Subsection 2.11.5. 


Bele, ALLOCATE Statements 


Definition: ALLOCATE statement 
ALLOCATE (control list) 


Definition: allocate control list 


FILE=string expression,NREC=numeric expression, 


A RECLEN=numeric expression[ ,LFN=numeric expression J 
A LRECFMT=string expression] [ORG=string expression ] 

A [,|KEYLEN=numerie expression] [ERL=statement label ] 

A LUNIT=numeric expression] [{JUNIT=numeric expression ] 


An ALLOCATE statement consists of the reserved word ALLOCATE followed by a 
control list, separated by commas and enclosed in parens. 


An ALLOCATE control list consists of the FILE (file name), NREC ‘number of records) 
and RECLEN (length of records) groups, plus other groups which are required for 
various file types. Optional groups' use, range and default values are found in Table 
2-12. 
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Table 2-13, ALLOCATE Controls 


Control group Range Default value 
Name and Use 


FILE=string expression up to 10 characters, required: no default value 
file name first one alphabetic 


NREC=numerie expression 0-65535 bytes (sequential) required: no default value 


number of records 1-65535 records (random, ISAM) 
RECLEN=numerie expression 0-255 bytes (sequential) required: no default value 
record length 1-512 bytes (random) 
2-512 bytes (ISAM) 
LFN=numeriec expression 1-specified maximum no file number specified 
logical file number (see Subsection 1.1) 
RECFMT=string expression "F"=fixed aye 
*record format "V"=variable 
ORG=string expression "S"=sequential ngi 
*file organization (type) "R"=random access 
"I"=ISAM 
KEYLEN=numeric expression 2-24 bytes (characters) no length specified 
key length 
ERL=statement label valid statement label no error trap set 
error line (up to 32 characters) 
UNIT=numerie expression 0 to 7 unit 0 
disk unit 
IUNIT=numerie expression 0 to 7 unit 0 


ISAM index disk unit 


ALLOCATE statements are used to create disk data files. The ALLOCATE statement 
reserves space on the diskette, adding the filename to the disk cirectorv. However, 
nothing is written in the file until it is opened and written. Since data files are of 
three types, sequential, random access and Indexed Sequential Access Method (ISAM), 
ALLOCATE statements come in three forms. 


* Both RECFMT and ORG groups check only the leftmost character in the string 


expression. Thus, "R" and "RAND" and "RANDOM" and "RUBBERDUCK" are 
equivalent as ORG specifiers: all specify random if used in an ORG group. 
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Table 2-14, ALLOCATE Record Sizing 


Field Format Size 
Type 
string constant default 1 byte/character 
X format length of format descriptor 
(String) (1 byte/X) 
string variable default 1 byte 
X format length of descriptor 
(String) (1 byte/X) 
string array default current length 
X format length of descriptor 
(String) (1 byte/X) 
numerie value default variable: up to 21 bytes 
(output as ASCII string 
as in PRINT statement: 
1 byte/character up to 21; 
includes leading blank, 
sign, exponent and so on) 
9 format 1 byte/9 or . 
(Numeric) (each 9 holds 1 digit) 
I format 1 byte/I; minimum 2, max- 
(Internal) imum 8 (1 I holds exponent 
and sign; each additional I 
holds 2 digits) 
P format 1/2 byte/P (. not output) 
(Packed) feach P holds 1 digit; 1 P holds 
sign if negative) 
Record Length Maximum length 
Type 


Sequential record 
(variable length) 


Random aecess record 


(fixed length) 


ISAM data files 


(fixed length) 


field length 


field length 


field length 


255 bytes 


512 bytes 


512 bytes 
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Name 


feature code 


erase line 
erase screen 
forward space 


printer form 


position 
tab 
backspace 
return 
linefeed 
formfeed 


clear screen 


2.11.1 ALLOCATE Statements 


Table 2-15, Video/Printer Control Function Sizing 


Control 
Code 


CF$(n) 


EL$ 

ES$ 

FS$ (n) 
PF$(x,y) 


CP$(x,y) 
TAB$(n) 
BS$ (n) 
CR$ 

LF$ (n) 
FF$ (n) 
CS$ (n) 


ASCII 
Sequence 


single byte 
special code 
ESC RS 


ESC GS 


ESC SP n times 


if y NE 0 
ESC LF y 

if x NE 0 
ESC SOH x 


Size 
In Bytes 


2 


2 


2*n (default is 2 bytes) 


wo 


ESC HT x ESC VT v 6 


ESC HT n 
BS n times 
CR 

LF n times 
FF n times 


FF (when n=0) 


“ESC ETX [=1) 


ESC EOT (n=2) 


13 


NNR 


(total: 6 bytes if both) 


(default is 1) 


(default is 1) 
(default is 1) 


‘default is 1) 


If video/printer control functions are sent to disk files instead of to the printer or 
video display (as, when a print file is "spooled" in multi-user applications, waiting for 
the printer to be free for output) the control functions are stored as strings of ASCII 


code as shown above. 


Thus, the EL$ function takes two bytes (for ESC and RS). 
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definition: _ ALLOCATE statement (sequential file) 


ALLOCATE (FILE=string expression,RECLEN=numeric expression, 


An ALLOCATE statement when used for sequential data file allocation consists of the 
reserved word ALLOCATE followed by a control list enclosed in parens and separated 
by commas. The control list consists of the FILE (filename), RECLEN ‘record length), 
NREC (number of records), and optionally, the ERL (error line) or UNIT (disk unit) 
groups. 


Although the RECLEN and NREC groups are required for allocation of a sequential 
file, the file will not necessarily be divided into records of the specified number and 
length, since sequential files are made up of variable length records. Rather, the 
record length and record number are multiplied together to get the total file length 
needed. This total is used to insert the file into the disk in the smallest space in 
which it will fit. (See Table 2-14 ALLOCATE Record Sizing for more information.) 
In sequential files only, the RECLEN and NREC control groups can be equal to zero. 
If these groups are set at zero, the system file manager assigns the largest available 
space on the disk to the file. A later truncation close, once the indefinite length 
sequential file is written, can be used to release any unused disk space. 


The maximum record length for sequential files is 255 bytes. Each WRITE statement 
creates an additional record in the sequential file. Each record will be the length of 
the WRITE statement output (as adjusted for format: see Table 2-14) plus 1 byte. 
The 1 byte addition is used as a record header: the first byte of each sequential record 
holds the length of the record; data starts on the second byte of each sequential 
record. Except for direct examination of the file, however the record header is 
transparent to the user. Sequential files should be ALLOCATED without consideration 
of the single extra byte per record; the implementation of the ALLOCATE statement 
(and all other STAR BASIC I/O on the file) automatically accounts for the record 
header. 


Examples: 

$1: ALLOCATE (FILE="DATA01",RECLEN=200,NREC=100) 

$2: ALLOCATE (RECLEN=100,NREC=100,FILE="SEQFIL") 

$3: ALLOCATE (NREC=Recorcs,RECLEN=Rec.length,FILE=Name$) 
S4: ALLOCATE (RECLEN=A*D,NREC=RecotRd$,FILE=A$&B$+N) 


Example S1 allocates a 20 kilobyte sequential file, DATA01. 

Example S2 allocates a 10 kilobyte sequential file, SEQFIL 

Example S3 allocates a sequential file using numeric variables Records and Rec.length 
to determine file size and a string array, Name$, to hold the file name. 

Example S4 uses expressions to designate the three required controls. 
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NREC=numerie expression [,ERL=statement label ]L,UNIT=numeric expression ]) 
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S5: ALLOCATE (UNIT=1,ERL=Error.handle,1,FILE=N$,R ECLEN=50,NREC= 
100,ORG="S",RECFMT="V") 

S6: ALLOCATE (ERL=Help.107 ,FILE="DTEXT",ORG=D$,RECFMT=R$ 
NREC=N.number,RECLEN=L.number,U NIT=U.number) 

S7: ALLOCATE (ERL=IO.ER.23,FILE=-NAM$&E$,RECFMT=M$(N,1),NREC=Rec+Tex, 
RECLEN=TIk*List,U NIT=M$(U;1)+0,OR G=M$(031)) 


Examples $5, S6 and S7 include several controls which are not required. S5 designates 
disk unit 1 as the file's diskette, sets an error trap, uses a string array to hold the 
file name, creates a 5 kilobyte sequential file and explicitly designates file organization 
as sequential and record format as variable. S6 uses variables or arrays for each of 
the values except the file name, which is designated with a string constant, and of 
course, the error trap, which is always a statement label. S7 uses complex expressions 
for all controls except the error trap (which would not allow an expression, only a 
statement label) and RECFMT and ORG, which are designated with substrings (string 
array references). 


definition: ALLOCATE statement (random access file) 


ALLOCATE (FILE=string expression,RECLEN=numeric expression, 


NREC=numerie expression,RECFMT=string expression, 
ORG=string expression [,ERL=statement label] [UNIT=numerie expression ]) 


An ALLOCATE statement when used for random access data file allocation consists 
of the reserved word ALLOCATE followed by a control list, separated by commas and 
enclosed in parens. The control list consists of the FILE (file name), RECLEN (record 
length), NREC (number of records), RECFMT (record format), and ORG (file organ- 
ization) groups, plus two optional groups, ERL (error line) and UNIT (disk unit). 


Because random access files are fixed record length files, both NREC and RECLEN 
must be exact in random access file allocation. See Table 2-14 ALLOCATE Record 
Sizing for information on record size calculation. 


Because RECFMT and ORG default to "V" (variable) and "S" (sequential), both these 
groups must be used in random access file allocation, with values of "F" and "R", 
respectively. 


The optional ERL group can be used to set an error trap for I/O errors during the 
execution of this statement, if desired. The UNIT group can be used to allocate a 
file on unit 1 (or 2 or 3 if auxiliary drive is used). 


The maximum record length of random access files is 512 bytes. The minimum length 
is 1 byte. Since random access files use fixed length records, the record length is 
contained in the file's disk directory entry. Each record is read or written by record 
number; the system file manager multiplies the record number by the fixed record 
length to access the appropriate record. 
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Examples: 

Rl: ALLOCATE (FILE="RANFIL",NREC=250,RECLEN=100,RECFMT="F" 
eS ORG="R") 

R2: ALLOCATE (FILE=Name$,NREC=Num.Rec,RECLEN=Len.Rec, 

° RECFMT=F orm$,ORG=Type$) 

R3: ALLOCATE (FILE=N$&M$(J;1),NREC=N+R/K,RECLEN=R*B, 

7 RECFMT=T$(R;1),ORG=T$(B;1)) 

R4: ALLOCATE (NREC=A*B,RECLEN=C+D*E,ERL=I0O.ER.43, 


FILE=L$&R*(F+1),UNIT=U+I,R ECF MT=Apple$,OR G=Apple$(2)) 


Example R1 allocates RANFIL, with 250 records of 100 bytes each; fixed length records, 
random access file type. 

Example R2 allocates a file using a string array, Name$, to hold the file name, numeric 
variables Num.Rec for number of records and Len.Rec for length of records, and string 
variables (or arrays) Form$ for record format and Type$ for file organization. 
Example R3 uses expressions to designate each control. 

Example R4 uses two optional controls: ERL (to set an I/O error trap) and UNIT (to 
designate the disk unit to contain the file). Expressions are used to designate each 
control except ERL, which requires a statement label, and RECFMT and ORG, which 
are designated with string array references. . 


definition: ALLOCATE statement (ISAM file) 


ALLOCATE (FILE=string expression,LFN=numeric expression, 


. NREC=numerie expression,RECLEN=numeric expression, 
i. RECFMT=string expression,ORG=string expression, 

° KEYLEN=numeric expression [,ERL=statement_ label] 

’ [,UNIT=numeric expression |{ IJUNIT=numeric expression ]) 


An ALLOCATE statement when used for ISAM file allocation consists of the reserved 
word ALLOCATE followed by a control list separated by commas and enclosed in 
parens. The control list consists of the FILE (file name), LFN (logical file number), 
NREC (number of records), RECLEN (record length), RECFMT (record format), ORG 
(file organization), and KEYLEN (key length) groups, optionally followed by the ERL 
(error line), UNIT (data file disk unit) or IUNIT (index file disk unit) groups. 


All groups in an ISAM ALLOCATE statement are directed at the data (master) file 
except IUNIT and KEYLEN, which apply to the index file. KEYLEN (up to 24 characters) 
specifies the length of the file's index keys. IUNIT, if used, specifies the disk unit 
the index file will be allocated on (default is unit 0). 
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FILE specifies the ISAM file names (if NAME is the ISAM file name, NAME is the 
name of the index file and’ NAME@ is the name of the data file). LFN specifies a 
pair of logical file numbers (number and number+1) which are not currently assigned 
to an open file. 


NREC and RECLEN must be accurately calculated for the ISAM data file. See Table 
2-14 ALLOCATE Record Sizing for information on record size calculation. 


RECFMT must be set equal to "F" (ISAM data files, like random access files, are fixed 
record length files) ORG must be set equal to "I". 


ERL, if used, sets an I/O error trap. UNIT, if used, designates the disk unit of the 
data file (default is unit 0). IUNIT, as noted above, designates the disk unit for the 
index file (default is unit 0). ; 


The maximum length of ISAM data file records is 512 bytes. The minimum record 
length is 2 bytes. Since ISAM data files are fixed length, there is no record overhead 
within the record. ISAM data files are accessed through the system's ISAM file 
manager, by index key (or, in special cases, by a partial key and an I/O error trap: 
see Subsection 2.12.6). 


Examples: 

Tis ALLOCATE (FILE="IFILE1",LFN=3,NREC=300,RECLEN=100, 

s RECFMT="F",ORG="I" ,KEYLEN=15) 

12: ALLOCATE (LFN=F.number,NREC=R.number,RECLEN=L.number, 
. KEYLEN=K.number,FILE=Name$,RECFMT=Form$,ORG=Type$) 
13: ALLOCATE ‘NREC=A*B,RECLEN=C+D/E,LFN=F-G,FILE=H$&I$&J, 
s KEYLEN=K+L,RECFMT=M$,ORG=M$(2)) 

14; ALLOCATE (IUNIT=1,UNIT=K+1,LFN=R*P,ERL=IOER.78, 

A KEYLEN=K,RECLEN=R,NREC=N,FILE=N$,RECFMT=T$,ORG=R$) 


Example I1 allocates file IFILE1, using logical file numbers 3 and 4 (they must not be 
in use on any open file or an I/O error results), of 300 records of 100 bytes each, 
fixed length records of ISAM type, with each key being 15 characters long. 

Example I2 uses variables and arrays to designate the controls. 

Example I3 uses expressions. 

Example 14 uses three optional controls, IUNIT (index file disk unit), UNIT ‘data file 
disk unit) and ERL (error line), designating its controls in a varietv of ways. 


2.11.2 OPEN Statements 


definition: OPEN statement 


OPEN (open control list) 
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definition: open control list 


LFN=numeriec expression [,FILE=string expression ] 


“~ [,UNIT=numeric expression] [,IUNIT=numeric expression ] 
“” [,OPT=numeric expression ] [,ORG=string expression ][,ERL=statement label] 


An OPEN statement consists of the reserved word OPEN followed by a control list, 
separated by commas, enclosed in parens. 


An OPEN statement control list consists of the LFN and FILE control groups, plus 
several control groups which depend on the type of file being opened. Each control 
group consists of the appropriate reserved word followed by an equals sign = followed 
by an appropriate expression. Each group is separated from the next by a comma; 
parens enclose the set of control groups in an OPEN statement. The control groups' 
names and ranges are defined in Table 2-16 OPEN Controls. 


OPEN statements open files for use, assigning an identifying logical file number and 
an access mode to each file. Logical file numbers range from 0 to the maximum 
specified in configuration (see Subsection 1.1), with 0 reserved for the printer. A file 
may be opened under different file numbers at different times, but a logical file 
number associated with an open file is reserved for that file only until the file is 
closed. 


Opening The Printer 
definition:. OPEN (LFN=0) statement 


OPEN (LFN=numeric expression equal to zero [,ERL=statement label]) 


To open the printer, only a logical file number (LFN group) equal to zero is required; 
an error trap (ERL group) may be used to trap errors. 


Opening the printer sets the printer to its large font, 10 characters per inch, 132 
characters per line, 6 lines per inch, 66 lines per page. If these characteristics must 
be changed, the CS$ and PF$ functions are used in a WRITE statement: see Subsections 
2.10.3 and 2.10.5. 


In RUNB only, the keyword "R=1" has been added to the partition control file definition 
lines to direct printer output from that partition to the remote printer. An "OPT=1" 
has been added to the printer OPEN Statements to select remote printer for printed 
output; "OPT=0" selects the standard printer and will override an "R=1" partition control 
file specification until the printer is CLOSED. 


File OPEN statements vary slightly depending on whether the file is sequential, random 
access, or ISAM. The three forms are discussed separately below. 
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Table 2-16, OPEN Controls 


Control Group 


Name end Use Range Default Value 
FILE=string expression alphabet character followed by no default value 
file name up to 9 printable characters 
LFN=numeric expression 0-specified maximum (0=printer) no default value 
logical file number (see Subsection 1.1) 
ORG=string expression "S" = sequential i 
organization "R" = random 
"™" = ISAM 


OPT=numeric expression Sequential 
file access option 
0 
1 


read only 0 
write or rewrite only 

(from beginning of file) 
2 = write extend (from end of file) 


7 read only exclusive access 
Random 
¢ \ 3 = update (read or write) default is 0, 
(only legal option) which is illegal 
4 = read only access for opened 


files that are single-writer/ 
multi-reader. 

5 = single-writer/multi-reader access; 
allows read only access by other 
user who must open the file 
OPT=0 or 4. 

6 = update (read or write) 
exclusive access. 


2.11.2 OPEN Statements LANGUAGE 


Table 2-16, OPEN Controls (cont'd) 


Control Group 
Name and Use Range Default Value 


The following chart lists the allowed (OK) and disallowed (ERR) OPEN options for 
non-ISAM files. File access mode conflicts are reported as an error 12. 


ist User File OPEN’d with OPT= 


1 2 3 4 > 6 7 
@OkCRR CER OOK KOK RR 
znd User 1«ERROERRERRERRERRERRERR 
mevenct 2 «ERROR ERAGE ERA ER 
To Open 3 OK OERRERROK”COKSRRERR 
with # OK ERR CERRO OKC 
ots S$ OKERRCERROERR COKER ERR 
———- ERR ERR ERR EAR OGRR ERROR 

7 eR ERROR OERROERROERROERR 


a ee SS ee 
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Table 2-16, OPEN Controls (cont'd) 


Control Group 
Mame and Uae Range Default Value 
ISAM 
0 =~ read or write, multi-access 0 
1 =~ read only, multi-access 
2 = read or write, exclusive 


access 


3 = read only, exclusive access 

6 = fast sort, read or write, 
exclusive access 

7 = same as option 3 

10 = _ file cleared, read or write, 
exclusive access 

14 = file cleared, fast sort, read 
or write, exclusive access 

18 = _ single-writer/multi-reader 
other users must open 
file OPT=1 


all other numbers are illegal entries 


NOTE: READ ONLY means, writes to the file are not allowed. EXCLUSIVE ACCESS 
means, only one user may access the file. Exclusive use is required for CLOSE (delete), 
DATE and RENAME statements. FAST SORT means, delayed write buffering reduces 
the number of disk accesses; speeding sorts and other data manipulations. CLEAR 
FILE means, clear the contents of the file (for scratch file use primarily). This deletes 
all records but does not require that the file be reallocated. 


UNIT= numeric expression 0-7 0 


disk unit 
(data file unit for ISAM) 


IUNIT=numerie expression 0-7 0 
ISAM index file disk unit 


ERL=statement label 1-32 alphanumeries, the first no default 
error trap line alphabetic, or a numeric string 
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definition: _ OPEN statement (sequential files) 


OPEN (LFN=numeriec expression, FILE=string expression 


“~ [ ,OPT=numeric expression ] [,ORG=string expression ] 
Aw [,ERL=statement label] [,UNIT=numeric expression ]) 


When a sequential file is OPEN'ed, it is identified by its name and a logical file number 
(which cannot duplicate a logical file number of another open file) is associated with 
the file until it is CLOSE'd. The file is opened with a specific option set, designated 
by the OPT control. For sequential files, OPT values are as follows: 


Control Opti on 


OPT=0 read only (default value) 

OPT=1 write only (from beginning of file; write or rewrite mode) 
OPT=2 write only (from end of data; write extend mode) 

OPT=7 read only (exclusive access) 


The ORG group defaults to "S", sequential organization, so use of this group is optional 
(if it is used, it must say ORG="S" or some equivalent). The ERL group can be used 
to set an error trap, if one is desired. The UNIT group can be used if the file is not 
on unit 0 (i.e., UNIT=1 designates a file on disk unit 1). 


Examples: 

$1: OPEN (FILE="DATFIL",LFN=1) 

$2: OPEN (LFN=3,FILE="SEQFIL",OPT=1) 

$3: OPEN (OPT=2,LFN=13,FILE="DTEXT1") 

S4: OPEN (FILE=Name$,LFN=F.number,OPT=O.number) 

S5: OPEN (LFN=R*S,FILE=H$&R&D$,OPT=Noptt+F$+1) 

S6: OPEN (FILE="THIS.1",LFN=15,UNIT=1,OPT=2,ERL=Open.er1) 


Example S1 opens DATFIL as file 1 for reading. 

Example S2 opens SEQFIL as file 3 for an original write, or a full rewrite. 

Example S3 opens DTEXT1 as file 13 to write new material on the end of the file, 
adding it to previously written data. 

Example S4 uses variables and an array to designate controls. 

Example S5 uses expressions to designate controls. 

Example S6 uses two optional controls, ERL to set an error trap and UNIT to designate 
unit 1 as the file location. 


definition: OPEN statement (random access file) 


OPEN (FILE=string expression,LFN=numeric expression,ORG=string expression, 
Nn OPT=numeric expression [,ERL=statement label] [,UNIT=numeric expression] ) 
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When a random access file is opened, it is identified by name and a logical file number 
(which cannot be the same as an already open file's LFN) is associated with it. The 
file is opened with specific option set, designated by the following OPT controls: 


Control Option 


OPT=3 update (read or write) 

OPT=4 read only 

OPT=5 single-writer/multi-reader 

OPT=6 update (read or write) exclusive access 


The ORG control group must be used to designate file organization as "R" random; 
the value "R" can be contained in a variety of string expressions (and any character 
beyond the first is ignored). Optional ERL or UNIT groups can be used to set an 
error trap for I/O errors in this statement's execution or to designate a disk unit as 
the location of this file. 


Examples: 

Ris OPEN (FILE="RANFIL",LFN=4,OPT=3,ORG="R") 

R2: OPEN (LFN=7,OPT=3,FILE="RRFILE",ORG="R") 

R3: OPEN (OPT=Rand.opt,FILE=Name$,LFN=F.number,ORG=R$) 
R4: OPEN (FILE=K$&Y&R$,OPT=R*T,LFN=Order+1,ORG=Ran$+S$) 
R5: OPEN (FILE=N$,LFN=9,OPT=3, UNIT=U,ERL=10.17,ORG=R$) 


Example R1 opens RANFIL as file 4, update mode. 

Example R2 opens RRFILE as file 7, update mode. 

Example R3 designates the controls with variables and a string array. 

Example R4 designates its controls with expressions. 

Example R5 uses the ERL group to set an error trap and the UNIT group to designate 
the disk unit containing its file. 


definition: OPEN statement (ISAM files) 


OPEN (FILE=string expression,LFN=numeric expression,ORG=string expression 


Aw [,OPT=numerie expression ][ ,ERL=statement label ] 
A [,UNIT=numeric expression] [ ,IUNIT=numeric expression ]) 


When an ISAM file is opened, both data and index files are identified by the name of 
the data (master) file and a pair of free logical file numbers (a number, N, and the 
next file number, N+1) is associated with the two files until they are closed. The 
ORG group must be used to designate file organization as "I" ISAM (any string expression 
may be used to designate ORG="I"; any characters after the first are ignored). An 
optional ERL group can be used to set an I/O error trap. An optional UNIT group 
can be used to locate the data file on a specific disk unit (default is unit 0). An 
optional IUNIT group can be used to specify the index file's location (default is also 
unit 0). 
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Examples: 


Il: OPEN (FILE="IFILE1",LFN=3,ORG="I") 

12: OPEN (LFN=7,FILE="CUSMAS",OPT=2,ORG="I") 

13: OPEN (OPT=O.number,FILE=Name$,LFN=F.number,ORG=I$) 

14: OPEN (LFN=R+E,FILE=T$&F&S$,OPT=(S&K$)/B,ORG=I$+S$+1) 

I5: OPEN (FILE=N$,LFN=J,OPT=Option$,ORG=I$,U NIT=U,IUNIT=Index.U,ERL=IO.ERS5) 


Example I1 opens IFILE1 as file 3 (and 4) in normal (read and write) mode. 
Example I2 opens CUSMAS as file 7 (and 8) in exelusive use, read-write mode. 
Example [3 uses variables (and a string array) to designate controls. 

Example I4 uses expressions to designate controls. 

Example I5 uses three optional control groups: ERL to set an error trap, UNIT 
to designate the location of the data file and IUNIT to designate the location 
of the index file. 


2.11.8 CLOSE Statements 


definition: CLOSE statements 


CLOSE (close control list) 


definition: close control list 


LFN=numerie expression[,OPT=numerie expression] [,ERL=statement label] 


A CLOSE statement consists of the reserved word CLOSE followed by a control list 
separated by commas and enclosed in parens. 


A CLOSE statement control list consists of the LFN control group, optionally including 
the OPT (close option) and/or ERL (error line) groups, each group consisting of the 
reserved word followed by an equals sign = followed by an appropriate expression. If 
more than one group is used, they are separated by commas. Table 2-18 CLOSE 
Controls lists their names and ranges. 


The CLOSE statement is used to end use of files, freeing the LFN for re-use. Optionally, 
CLOSE statements will truncate unused space from the end of a sequential or random 
file, or delete a file altogether. ISAM files must be open in an exclusive use mode 
to be deletion closed. An attempt to close delete an ISAM file which is not open for 
exclusive access results in an I/O error. 
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Table 2-18, CLOSE Controls 


Control group 


Name und use Range Default value 
LFN=numerie expression 0-specified maximum (0=printer) no default value 
logical file number (see Subsection 1.1) 
OPT=numerie expression 0 = normal close 0 
close option 1 = deletion close (file killed)* 
2 = truneation close (unused 


space at the end of a 
sequential file eliminated; 
eannot be used with random 
or ISAM files) 


ERL=statement label valid statement label no default value 
error trap target line (alphabetic followed by up 
to 31 alphanumeries, or 
string of numerics) 


*ISAM files must be open for exclusive access (OPT=2, 3, 6, 7, 10, or 14) 
to be deletion closed. An attempt to close delete an ISAM file which 
is not open exclusive access results in an I/O error. 


Examples: 

C1: CLOSE (LFN=5) 

C2: CLOSE (LFN=3,OPT=1) 

C3: CLOSE (OPT=2,LFN=11) 

C4: CLOSE (LFN=F.number,OPT=O.number) 
C5: CLOSE (OPT=R$*1,LFN=VAL(M$(J;1)) 
C6: CLOSE (LFN=Num,ERL=IO.ER8) 

C7: CLOSE (OPT=N17,LFN=N22,ERL=I076) 


Example C1 closes (normally) the file open as LFN 5. 

' Example C2 close deletes LFN 3. 

Example C3 close truneates LFN 11. 

Example C4 uses variables to designate both LFN and OPT. 

Example C5 uses expressions to designate control values. 

Example C6 uses the OPT default value of 0 (normal) and sets an error trap with the 
ERL group; LFN specified by value of a variable. 

Example C7 uses variables to set LFN and OPT, sets an error trap at IO67 with the 
ERL group. 
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2.11.4 RENAME Statements 


definition: RENAME statement 


RENAME (rename control list) 


definition: rename control list 


LFN=numeric expression,FILE=string expression[,ERL=statement label ] 


A RENAME statement consists of the reserved word RENAME followed by a control 
list, separated by commas and enclosed in parens. 


A RENAME control list consists of the LFN and FILE groups, separated by a comma, 
optionally adding the ERL group. In each case, the group consists of the reserved 
word followed by an equals sign = followed by an appropriate expression. 


The RENAME statement changes the name of the file designated by the logical file 
number (it must therefore be an open file) to the new name contained in the string 
expression of the FILE group. The ERL (error line) group, if used, designates a line 
which will receive control if an I/O error occurs during execution of this statement. 


ISAM files must be open in an exclusive access mode (OPEN OPT=2, 3, 6, 7, 10 or 
14) to be renamed. An attempt to rename an ISAM file which is not open in an 
exclusive access mode results in an I/O error. 


Examples: 

R1: RENAME (LFN=6,FILE="BACKUP1") 

R2: RENAME (ERL=IOR2,LFN=9,FILE="D10179") 
R3: RENAME (FILE=Name$,LFN=F.number) 

R4: RENAME (LFN=File1,FILE=Bname$,ERL=R4) 
R5: RENAME (FILE=D$&b&F$,LFN=T+S$) 


Example R1 renames file 6 BACKUP1. 

Example R2 renames file 9 D10179, with an error trap at IOR2. 

Example R3 uses a numeric variable and a string array to designate control values. 
Example R4 also uses a variable and an array to set file name and LFN; it also sets 
itself as its own error trap. This procedure is obviously dangerous, since a continuing 
I/O error would lead to endless looping. 

Example R5 uses expressions to designate control values. 
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2.11.5 DATE Statements 


definition: DATE statement 


DATE (date control list) 


definition: date control list 


LFN=numerie _expression[,ERL=statement label 


A DATE statement consists of the reserved word DATE followed by a control list 
enclosed in parens. 


A DATE statement control list consists of the LFN group and, optionally, the ERL 
group with a comma separating the two groups. In each case, a group consists of the 
reserved word, an equals sign = and an appropriate expression, in that order. 


The DATE statement adds the current date, taken from the system's internal clock, 
to the file designated by the logical file number (which therefore must be an open 
file). The optional ERL group designates a line which will receive control if an I/O 
error occurs during execution of this statement. 


An ISAM file must be open in exclusive access mode (OPEN OPT=2, 3, 6, 7, 10 or 
14) to be dated. An attempt to date an ISAM file which is not open in exclusive 
mode results in an I/O error. 


Examples: 

Di: DATE (LFN=6) 

D2: DATE (LFN=9,ERL=IOD2) 

D3: DATE (LFN=F.number,ERL=ER.17) 
D4: DATE (LFN=R*T,ERL=IOD4) 


Example D1 dates file 6. 

Example D2 dates file 9, sets an error trap at IOD2. 

Example D3 uses a variable to designate the file number, sets an error trap at ER.17. 
Example D4 uses an expression to designate file number, sets an error trap at IOD4. 


2.12 FILE RECORD INPUT/OUTPUT 


Where file externals deal with a file as a whole, file record I/O statements are active 
only on small parts of a file at any given time, reading, adding, changing or deleting 
single records and data items. 


As in file external directives, the file record I/O statements use the same directive 
for all three types, with a control list which varies according to whether the file is 
sequential, random access or ISAM. Where the syntax varies substantially, a separate 
definition for each type of file is given after the record I/O statement's general 
definition. 
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READ statements are used to obtain data from disk files, (in addition to their role in 
internal I/O, which was discussed in Subsection 2.9.1). Their use in file record I/O is 
discussed in Subsection 2.12.1. 


WRITE statements send data to disk files, adding or changing records. Their use in 
file record I/O is discussed in Subsection 2.12.2. (Their use in I/O with the printer 
was discussed in Subsection 2.10.3.) 


DELETE statements delete individual records from data files. Their use is discussed 
in Subsection 2.12.3. 


An ISAM record must be locked (the result of a READ statement) to be modified. 
However, reeords are sometimes read but then not written to; to free such records, 
the UNLOCK statement is used. Use of UNLOCK statements is discussed in Subsection 
2.12.4. 

REWIND statements return the read and write pointers to the logical beginning-of- 
information point in sequential and ISAM files. Their use is discussed in Subsection 
2.1256 

Because the keys of ISAM files are sorted automatically by the ISAM file manager in 
ASCII collating order, ISAM files are ideally suited for data sorting. Several examples 
of the use of ISAM files in data manipulation are given in Subsection 2.12.6. 

2.12.1 READ Statements 


definition: READ statement (file record I/O) 
READ (read control list) [variable list ] 


definition: read control list (file record I/O) 


LFN=numeric expression[,ABSOLUTE=1 [,UNIT=numeric expression |] 
n [,EOF=statement label][,ERL=statement label | 
[ ,KEY=string expression][ ,REC=numeric expression] 


[,LOCK=numerie expression][,MODE=string expression | 
| FORMAT=string expression] [IOLIST=statement label | 


A READ statement consists of the reserved word READ followed by a control list, 
separated by commas and enclosed in parens, followed by a variable or list of variables 
separated by commas. 
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A READ statement control list consists of the LFN group and, optionally, a list of 
other control groups. The READ control groups and their use are listed in Table 2-19 
READ Controls. (The READ statement is also used, with a smaller set of controls, 
for internal I/O: see Subsection 2.9.1.) 


The READ statement is used to transfer values from data files into variables or array 
references. The values which are read must match in both number and type the 
variables (or array references) into which they are read. In other words, if the variable 
list has five items, the first three numeric variables and the last two string arrays, 
there must be five values in the record, the first three numeric and the last two 
string. 


In practice, records are often written as a single string array, which is then broken 
into substrings for data manipulation. Substantial file space savings can be made 
through the use of the FORMAT group for controlling numeric value storage, however, 
in which case the FORMAT descriptors used in both READ and WRITE statements 
must match in type or an I/O error will result. 


The LFN control group is always present in READ statement control lists to identify 
the file being read. The error handling control groups (EOF, end of file; and ERL, 
error line) are always optional but are frequently used with all three types of files. 
Likewise, the FORMAT group is always optional but frequently used with all three 
types of files (see Table 2-4). The MODE group is also used with all three types of 
files, with some restrictions (see Table 2-20). KEY and LOCK are used only with 
ISAM files, to specify the index key and to optionally leave a record locked or unlocked 
after the read. REC is used only with random access files, to specify the number of 
the record to be read. Table 2-19 lists the controls and their ranges and default 
values. 
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Control group 
Name and use 


Table 2-19, READ Controls 


Range 


Default value 


LFN=numerie expression 
logical file number 


MODE=sstring expression 


access mode 
(see Mode Table) 


FORMATs=string expression 


input data format 


EOF=statement label 
end-of-file trap 


ERL=statement label 


general I/O error trap 


1-specified maximum 
(see Subsection 1.1) 


"S" = sequential 
"R" = random 
special characters 


(see FORMAT Table) 


valid statement label 


valid statement label 


no default value 


ton 


same as PRINT 
statement 


automatic system 
action 


automatic system 
action 


no default value 


2-24 characters in length 
(if MODE="S", key must 


KEY=string expression 
o key to ISAM file 
be a string array name) 
REC=numeric expression 1-65535 
random file record number 


no default value 


LOCK=numerie expression 0 = unlocked 1 
ISAM record lock 1 = locked 


IOLIST=statement label 
supplies variable list 


label of an IOLIST statement defaults to variable 
list required 


ABSOLUTE=1 i defaults to normal 
disk sector read file read 
UNIT=numerie expression 0-7 0 


supplies unit number 
for ABSOLUTE read only 


Note: When the ABSOLUTE parameter is used, REC must be used to specify 
the sector to be read; REC range then becomes 0 to disk size (in blocks). 
The UNIT group may only be used with the ABSOLUTE group. 
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Table 2-20, READ Modes 


File is: Mode is: Operation is: 

Random "RM read by record number 

Random tS! read sequentially by record number order 
ISAM “EY read by key value 

ISAM ng read next record (by key order) 
Sequential “a illegal - 

Sequential is! read next record 


definition: | READ statement (sequential file) 


READ (LFN=numeric expression ,MODE=string expression ] 
[,EOF=statement label] [,ERL=statement label] [,IOLIST=statement labell 


> 


[ ,FORMAT=string expression])[ variable list ] 


> 


When a sequential file is read, the LFN group is required to identify the file (it must, 
of course, be open). MODE defaults to "S" sequential, so it is optional. The two 
error groups, ERL and EOF, are optional but frequently used, as is the FORMAT group. 
If a FORMAT is used to output file records, it must be used to read it as well. 


The IOLIST group may be used to replace the statement's variable list with a standard 
list from an IOLIST statement in the routine. If IOLIST is used, the statement's 
variable list need not be used; if IOLIST is not used, then the statement's variable list 
must be used. If both IOLIST and: an intrinsic variable list are used, the IOLIST is 
used first. 


Disk files store string data as strings of character codes. String data will be read 
into string arrays until the first array is filled, whereupon the next array will be filled. 
If more than one string is to be read from a record, either the FORMAT control group 
must be used to specify the length of each string, or the arrays must be exactly long 
enough to hold their field and each field must be fixed in length. 


A common practice provides a third alternative: if records are read and written as 
a single string array, with data fields being separated by the program after I/O, then 
neither the FORMAT nor the array length matching will be necessary. 


Examples: 

S1: READ (LFN=7,EOF=End.Loop,ERL=IOS1) R37,R38,R$ 

$2: READ (EOF=EFS2,ERL=IOS2,LFN=Group,IOLIST=List2) 

$3: READ (EOF=EN.S3,ERL=IO.ER.S3,LFN=F.num,FORMAT="X(10),99.99, 
X(*)") F$,NumT,R$ 

$4: READ (FORMAT=A$&D$&N1$&"999.99",LFN=T+3,ERL=IOA) 


M$(J;A),Y$,Full,SubT(J) 


\ 4 


LANGUAGE 2.12.1 READ Statements . 


o 


Example S1 reads file 7, setting both an end-of-file and an 
I/O error trap, reading the current record into two numeric 
variables and a string array. Example S2 uses a numeric 
variable to designate LFN, sets both an end-of-file and an 
I/O error trap, and reads the current record into an IOLIST 
at List2. Example S3 uses a variable to set LFN, uses both 
error groups, and uses the optional FORMAT group to read 
the current record into a string array, a numeric variable 
and another string array. Example S4 uses expressions to 
specify LFN and FORMAT, sets only an ERL I/O error trap, 
and reads the current record into a string array reference, 
a string array and a numeric variable and a numeric array 
reference. 


Sequential files are read according to the record pointer. When a sequential file is 
opened for reading, the pointer is set at the first record in the file. When a record 
is read, the pointer moves to the next record in the file. The pointer can be positioned 
at the beginning of the file after one or more reads through a REWIND statement 
(see Subsection 2.12.5). Sequential records must always be read in the order in which 
they were written, which is why sequential files are useful as text storage files for 
information which is not accessed frequently and is always accessed in the order 
written. 


definition: READ statement (random access file) 


READ (LFN=numerice expression [, MODE=string expression ] 
a [,REC=numeric expression ][,FORMAT=string expression] 


“a 


[ ,IOLIST=statement label ][,EOF=statement label] [,LOCK=numeric expression] 


a [,ERL=statement label]) [variable list ] 


When a random access file is read, LFN is required to identify the file. The type of 
read is determined by the MODE group. If MODE="S", the file will be read sequentially 
by record number order and the REC group is superfluous. If MODE="R", then the 
file will be read randomly, by record number, and REC is required to give the record 
number. 


The optional FORMAT group can be used to specify the data format; if a FORMAT 
group was used in output, it must be used on input. In addition, string data in files 
is held as a set of ASCII character codes. If more than one string array is present 
in the variable list, the first one will receive data until its full length is filled; then 
the data will be inserted in the next array, and so on. If more than one string field 
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is present in a record, either the FORMAT group must be used to separate the field, 
or the string arrays must be dimensioned exactly and each field must be of specified 
length. A third alternative is to use a single string array to hold a record. In that 
case, the various data fields are separated by the program, after the data is read. 


The optional IOLIST group replaces the variable list. If IOLIST is used, the variable 
list will be taken from a labeled IOLIST statement. If the IOLIST group is used, the 
variable list need not be used; if the IOLIST group is not used, then the variable list 
must be used. If both IOLIST and an intrinsic variable list are used, the IOLIST is 
used first. 


The two error groups are always optional but frequently used. EOF traps an end-of-file 
condition (record number too high, or end-of-file reached in a series of MODE="S" 
reads). ERL traps all I/O errors in the execution of the read. 


As with ISAM files, reading a random access file randomly with the LOCK parameter 
set at 1 (the default value) locks the record being read until another operation is 
performed on the file by the same user. A locked record cannot be read or written 
by another user in a multi-tasking environment until it is unlocked. Unlike ISAM files, 
records in a random access file need not be locked to the rewritten—locking is a 
purely protective procedure aimed at keeping one user in a multi-user system from 
rewriting or deleting a record another user is currently reading. See Appendix C for 
a discussion of multi-user programming. Note that reading a record sequentially 
(MODE="S") does not lock records in random access files. 


Examples: 


Ri: READ (LFN=3,REC=54,MODE="R") A$ 

R2: READ (LFN=5,MODE="R",REC=34,FORMAT="IIII, X(20), 

A IMI") N32,D$N2 

R3: READ (FORMAT=D$,LFN=F.num,REC=J,MODE=M$) Trap,Dum$ 

R4: READ (LFN=N9,REC=N00,FORMAT=T$&R$,MODE=R$&F$,ERL=Er.1, 
A EOF=EdRD,IOLIST=RLIST13) 

R5: READ (REC=T+E/F,LFN=O/I1,MODE=R$(I;13), FORMAT=R$&T&F$, 

A ERL=ER2,EOF=ENT) N,A$ 


Example R1 reads record 54, file 3 into a string array. 

Example R2 reads record 34, file 5 into two numeric variables and a string array, 
using a string constant to specify the three formats. 

Example R3 uses variables and arrays to specify controls. 

Example R4 uses variables and expressions to specify controls, an IOLIST specifies the 
variable list and two error groups are used to trap for end-of-file errors at EdRD and 
other I/O errors at Er.1. 

Example R5 uses complex expressions to designate control values, and sets two error 
traps. 


Random access files are read either randomly by record number or sequentially by 
record number order. Random access files are useful for storage of frequently 
referenced material which can be fitted into a fixed record format. However, its use 
is overshadowed by the many advantages of ISAM files, which allow all of the operations 
allowed in random access files, plus many more. 
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definition: READ statement (ISAM file) 


READ (LFN=numeric expression,KEY=string expression|,IOLIST=statement label | 


, LMODE=string expression ][,FORMAT=string expression ] 
, EOF=statement label][,ERL=statement label ] 


, ,.LOCK=numeric expression ]) [variable list] 


ISAM files are automatically maintained by the system ISAM file manager. Keys are 
held in ASCII collating order and records are organized in that order. 


ISAM files ean be read in two modes, sequentially (by key order) or randomly (by key). 
If an ISAM file is read sequentially, the record pointer is set to the beginning of the 
file when the file is opened. (The REWIND statement can be used to reset this pointer 
to the beginning of the file after several reads have taken place: see Subsection 2.12.5.) 
As each record is read, the key is sent to the KEY group expression. If a string 
array is used in the KEY group, the value of the key will be inserted into the array 
and can be referenced and tested internally, or displayed on the video or printed on 
the printer, through normal uses of that array. However, if a complex string expression 
were used instead of an array, the value of the record's key would be discarded. 


If an ISAM file is read randomly, the function of the KEY group is reversed. The 
value of the KEY string expression is used to find the matching key in the index file, 
which then allows access to the record sought. (A combination of random and sequential 
access can be used to allow search by a partial key: see Subsection 2.12.6 for an 
example of this use.) 


Since the MODE group defaults to "S", it need not be used in sequential-mode ISAM 
reads. LFN is required to identify the file being read, while the KEY group is required 
to supply a string expression to hold the key value being read. 


In random-mode reads, the MODE group must be present to specify "R" mode (a 
complex expression may be used to hold this value, if desired). The LFN group must 
be present to identify the file, and the KEY group must be present to identify the 
record. 


EOF and ERL groups are frequently used, to trap end-of-file and other I/O errors. 


The FORMAT group is also optional, defaulting to 1 byte/ASCII character output format 
(see Table 2-14 ALLOCATE Record Sizing for a discussion of FORMAT descriptor 
storage characteristics). As noted above, regardless of the type of file being read, 
the FORMAT descriptor must be of the same type in both READ and WRITE statements 
for file record I/O or an I/O error will result. 
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The optional IOLIST group may be used to specify an IOLIST statement holding the 
variable list. If the IOLIST group is used, the READ statement need not contain a 
variable list; if the IOLIST statement is not used, the READ statement must contain 
a variable list. If both are used, the IOLIST is used first, then the intrinsic variable 
list. 


The LOCK control group is also optional, defaulting to 1 (record locked). ISAM records 
cannot be modified (that is, rewritten or deleted) unless the record is locked. Only 
1 record per file per user can be locked at any time. 


A record can only be locked by being read with the LOCK set to 1. Any operation 
on the file after the lock is placed on a record unlocks that record (in other words, 
there can be no intervening operations on that file between a READ (lock) and the 
corresponding WRITE, or the record will be unlocked). An attempt to WRITE an 
unlocked record results in an I/O error. 


If a READ of a record locks that record, but examination of the record causes no 
WRITE to follow (it was the wrong record, say), the record can be unlocked by a 
subsequent READ or DATE or other statement affecting that file, or by an UNLOCK 
statement (see Subsection 2.12.4). 


A new record can be written without being locked (since it cannot be read before it 
is first written, after all). 


Examples: 
IVs READ (LFN=3,KEY=K$) R$ 


12: READ (LFN=1,KEY="INITIALIZE ",MODE="R") Ar$ 
I3: READ (LFN=F.num,KEY=P$&F$,MODE=M$(K3;I),FORMAT=Form$, 


A LOCK=0,ERL=ER2) Subt.Fr$ ; 
14: READ (LFN=T+D,KEY=Tres$, MODE=M$,FORMAT=F$,EOF=Endlt, 
A ERL=Help1) H,I,J,K,D$ 


Ee I1 reads the next record in file 3, putting the key in K$ and the record 
in R$. 

Example I2 reads the INITIALIZE record from file 1 into Ar$. 

‘Example I3 uses variables, arrays and expressions to designate controls; the record is 
left unlocked; an error trap for I/O errors is set at ER2. 

Example I4 uses expressions, variables and arrays to designate controls; record is locked 
by default; both an end-of-file (at EndIt) and an I/O error trap (at Help1) are set. 
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definition: READ statement (ABSOLUTE) 


READ (ABSOLUTE=1,REC=numeric expression [,FORMAT=string expression ] 


A [ IOLIST=statement label] [UNIT=numeric expression ] 
A | [,ERL=statement label]) [variable list] 


The ABSOLUTE mode READ statement in effect treats the entire diskette as a single 
random access, fixed record length file, with each record being 512 bytes. 


The ABSOLUTE control group is required to perform ABSOLUTE mode READ's. The 
REC control group is required to give the sector number which will be read. Unlike 
other READ statements (which use LFN's from an OPEN statement to provide the disk 
unit specifier), ABSOLUTE READ's use the UNIT control group to specify the unit to 
be read. As always, the disk unit defaults to unit zero, so that UNIT control group 
is required only if a unit other than zero is to be read. 


The other control groups are used in the same way in ABSOLUTE reads as in the 
other types of disk access. FORMAT provides format designators to allow use of the 
I (internal) and P (packed) numeric storage formats; IOLIST provides a list of variables 
into which the data will be read; ERL provides an error trap if an error occurs during 
execution. (ABSOLUTE mode uses a special set of error numbers, 0 - 5; see Appendix 
A.) As with the other types of READ usage, if both an IOLIST and the intrinsic 
variable list are used, the IOLIST will be used first, followed by the variable list. 


ABSOLUTE reads may use more than one variable to hold the 512 bytes of data in 
the sector being read, and need not provide enough variable space for all of the read 
data. However, the special case of reading into a variable which has been DIM'ed at 
512 bytes is substantially faster than any other type of READ; this speed advantage 
normally more than compensates for any data manipulation needed to break the 512 
byte string into its component data fields. 
Examples: 
READ (ABSOLUTE=1,REC=457) A$ 
READ (FORMAT=Form$,UNIT=1,IOLIST=RList7,REC=N+R/5,ABSOLUTE=1) 
READ (ABSOLUTE=1,IOLIST=InHold,R EC=Index,ERL=ReadError) Holder$ 
2.12.2 WRITE Statements 


definition: WRITE statement 


WRITE (write control list) Lexpression list ] 
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definition: write control list 


LFN=numerie expression 
[ ,EOF=statement label] [,ERL=statement label] 


> 


A [ ,KEY=string expression ],REC=numeric expression] 
A [ MODE=string expression ] [FORMAT=string expression] 
A [ JOLIST=statement label ][ ,ABSOLUTE=1[ ,UNIT=numerie expression ] ] 


A WRITE statement consists of the reserved word WRITE followed by a control list, 
separated by commas and enclosed in parens, optionally followed by one or more 
expressions (either string or numeric), separated by commas if more than one. 


A WRITE statement control list in file I/O always includes the LFN group to identify 
the file into which a record is to be written. REC, KEY and MODE groups are 
required for certain operations with the three types of files (each file type, sequential, 
random and ISAM, is discussed separately below). FORMAT, IOLIST and the two error 
groups, EOF and ERL, are always optional but are frequently used. 


WRITE statements are also used for printer I/O, with a smaller control list. See 
Subsection 2.10.3 for a discussion of this use. 


The WRITE statement is used to output values to disk and to disk files. The values 
of the expressions on the expression list are written on the file as a single record. 
The control list of the WRITE statement varies according to the type of file being 
written to and the type of I/O desired. These are examined separately below. 


The WRITE control groups mateh the READ statement control groups. Tables 2-21, 
2-22 and 2-4 list the WRITE control groups, their ranges and default values. 
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Table 2-21, WRITE Controls 


Control Group 


Name and Use Range Default Value 


LFN=numerie expression 0-specified maximum (0=printer) no default value 


logical file number (see Subsection 1.1) 
MODE=string expression "S" = sequential "gS" 
access mode "R" = random 
(see Mode Table) 
FORMAT=string expression special characters same as PRINT 
output data taeiant (see FORMAT Table 2-4) statement 
EOF=statement label valid statement label no default value 


end-of-file error trap 


ERL=statement label valid statement label no default value 
general I/O error trap 


KEY=string expression 2-24 characters in length no default value 
key to ISAM file 

REC=numeric expression 1-65535 no default value 
random file record number 

IOLIST=statement label label of an IOLIST statement defaults to expression 
supplies expression list list required 

ABSOLUTE=1 1 defaults to normal 
disk sector read file write 

UNIT=numeric expression 0-7 0 


unit number 
for ABSOLUTE write only 


Note: When the ABSOLUTE parameter is used, REC specifies which sector is to be 
written. REC range then become 0 to disk size. The UNIT group may only be used 
with the ABSOLUTE group. 
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Table 2-22, WRITE Modes 


File Type Mode Designation Operation 
Random access a write by REC record number 
"sg" write next record (by record number sequence) 
Sequential "Rh? illegal 
ng" write next record 
ISAM “Es rewrite current record (last record read) 
"gs" write-add by KEY value 


definition: WRITE statement (sequential file) 


WRITE (LFN=numeric expression [,FORMAT=string expression ] 
A [,MODE=string expression][,IOLIST=statement_ label ] 


[,EOF=statement label][ ,ERL=statement label])[ expression list ] 


> 


When a sequential file record is written, the LFN group is required to identify the 
file being addressed. The file's access mode (set in the OPEN statement) determines 
where the record is to be written. If the file is in write-rewrite mode, the new record 
will be written at the point designated by the file's record pointer (which is set to 
the beginning of the file when the file is opened). If the file is in write-extend mode, 
the new record will be written immediately after the last previous record in the file. 


Sequential file WRITE statements must have MODE="S" (sequential). Since this is the 
default value for MODE, the MODE group would not normally be used in sequential 
WRITE. MODE ean be used; if MODE="R" (random) in a sequential WRITE, an I/O 
error will result. 


The optional error groups can be used to trap end-of-file and I/O errors. 


The optional FORMAT group can be used to specify output format (see Subsection 
2.10.4.1). If a format descriptor is used in a WRITE statement, a descriptor of the 
same type must be used to READ that record (see Table 2-4). The optional IOLIST 
group can be used to specify an IOLIST statement containing the expression list. If 
IOLIST is used, the WRITE expression list need not be used. If both are used, the 
IOLIST is output first, then the intrinsic expression list. 
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Examples: 

Sl: WRITE (LFN=14,IOLIST=LIST5) 

$2: WRITE (LFN=2,FORMAT="99.99,X(20), III, X(*)") 
SubT* Deb,Cus$,Tnum,D$&F$&R$&S$ 

83: WRITE (ERL=ER5,EOF=E.loop,LF N=K+Rst,MODES=S$, 


FORMAT=D$&F$)T*S/M+1,R$&G/D&J4 


Example S1 writes the IOLIST expressions to the current record of file 14. 

Example S2 writes a set of expressions' values to file 2's current record, using format 
as specified in a string constant. 

Example S3 uses variables, arrays and expressions to designate controls; sets both EOF 
and ERL error traps; sends the values of two complex expressions to the designated 
record. 


definition: | WRITE statement (random access file) 


WRITE (LFN=numeric expression, [REC=numeric expression ] 


A [,MODE=string expression] [,FORMAT=string expression ] 
A [,IOLIST=statement label ] [ERL=statement label ] 
A [,EOF=statement_label]) [expression list ] 


When a random file record is written, the following groups are required: LFN identifies 
the file. MODE chooses the file write mode: if MODE="R", the record will be 
identified by the value of the REC group expression; if MODE="S" the next record, 
by record number sequence, will be written and the REC group is unnecessary. 


The optional ERL and EOF groups trap errors. ERL traps all errors, while EOF traps 
only end-of-file errors. Note that error 23 (record locked) is possible with random 
access files when writing randomly (MODE="R"), but that error 24 (record not locked) 
is not possible, since unlike ISAM files, random access records need not be locked to 
be rewritten. 


The optional IOLIST group specifies an IOLIST statement holding an expression list for 
the WRITE statement. If the IOLIST group is used, the WRITE statement expression 
list need not be used; if the IOLIST is not used, the expression list must be used. If 
both are used, the IOLIST is used first. 


The optional FORMAT group specifies format of the output data. See Table 2-4 for 
the various FORMAT specifications available. If a record is written with a FORMAT 
specification, a matching FORMAT specification will be required to read it. 


Examples: 

R1: WRITE (LFN=11,REC=23,MODE="R") R*S,T$&Y$ 

R2: WRITE (REC=R.num,LFN=F.num,MODE=M$,FORMAT="IIIII, 

A X(10),999.99" IOLIST=RLIST12) 

R3: WRITE (MODE=I$(K,L),REC=R(J,L), LF N=U$+0,FORMAT=T$&D$&T$L, 
uy ERL=ER7) Ap*Ws3,Q$,I 

a WRITE (LFN=K,REC=R*Num3,FORMAT=F orm$,MODE=R$,EOF=EF4, 


ERL=ER9) R$(Index;Jind) 
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Example R1 writes the values of two expressions to record 23, file 11. 

Example R2 uses variables to designate controls, with a string constant giving the 
value of the FORMAT group and an IOLIST statement holding the expression list. 
Example R3 uses array references and expressions to designate controls; sets an error 
trap for I/O errors; writes the values of a numeric expression, a string array and a 
numeric variable to the record in the random access file. 

Example R4 uses variables, expressions and string arrays to set controls; sets an 
end-of-file error trap at EF4 and a general I/O trap at ER9; writes a string array 
reference to the record. 


definition: WRITE statement (ISAM file) 


WRITE (LFN=numeric expression[,KEY=string expression ] 
A  _[,MODE=string expression] [FORMAT=string expression] [ ,IOLIST=statement_ label] 
A [,EOF=statement_label][,ERL=statement label] ) [ expression list ] 


To write an ISAM record, the following control groups are required: LFN. LFN 
specifies which file. KEY specifies the key of the record to be written; it is not 
required on MODE="R" WRITE's. 


MODE="S" must be specified to write-add, that is, to add a new record to an ISAM 
file. (MODE="S" is the default value, so it may be specified by leaving out the MODE 
group). MODE must be "R" to rewrite a record, and the record must be locked (i.e. 
the record must have been immediately previously read, with the LOCK option at 1) 
to write in MODE "R" to an ISAM file. 


FORMAT may be used to specify the format of the output data. See Table 2-4 for 
FORMAT specifiers. 


IOLIST may be used to specify an IOLIST statement containing an expression list. If 
the IOLIST group is used, the WRITE statement's expression list need not be used; if 
IOLIST is not used, the WRITE statement's expression list must be used. If both are 
used, the IOLIST is output first. 


The optional EOF and ERL groups may be used to trap errors. EOF traps an end-of-file 
error, while ERL traps all I/O errors (including EOF if EOF is not specified). 


Examples: 
Il: WRITE (LFN=3,KEY="INITIALIZE " MODE="S",FORMAT="IIIIIII, X(*)", 
iA EOF=RecEnd,ERL=BackTolt) S(T,R)*N$(7,R;J)+N,Apple$&G&Due$ 


12: WRITE (LFN=F.num,KEY=Key3$,MODE=Ran$,FORMAT=Form$,EOF=En3, 

A ERL=B4N2,IOLIST=List12) 

13: WRITE (KEY=N$&T&E$,LFN=R/K,FORMAT=T&R$&T$,MODE=M§$(J3L), 

A EOF=Back,ERL=Again)Day(D,M),Week(Monday, Y ear), Quarter(Subtotal) 


2-150 REV. B 


LANGUAGE 2.12.3 DELETE Statements 


Example I1 uses constants to set controls, writing record INITIALIZE in file 3 with 
format designated; setting end-of-file trap at RecEnd, I/O error trap at BackTolt; 
writing the values of two complex expressions. 


Example [2 uses variables and string arrays to set controls; sets two error traps; writes 
from an IOLIST at List12. 


Example I3 uses expressions to set controls; sets two error traps; writes three numeric 
array reference values to the file. 


definition: WRITE statement (ABSOLUTE) 


WRITE (ABSOLUTE=1,REC=numeric expression LFORMAT=string expression ] 


A [,IOLIST=statement label] LUN IT=numerie expression ] 


> 


LERL=statement label]) [expression list] 


The ABSOLUTE mode WRITE statement in effect treats the entire diskette as a single 
random access, fixed record length file with each record being 512 bytes (a sector). 


The ABSOLUTE control group is required to perform ABSOLUTE mode writes. The 
REC control group is required to specify which sector is to be written. If the data 
is not directed at disk unit zero, the UNIT control group is required to specify the 
disk unit. 


The other control groups are used just as in other types of WRITE statements. FORMAT 
is used to specify output data formats; IOLIST supplies a list of expressions to be 
output; and ERL sets an error trap. (ABSOLUTE mode uses a special set of error 
numbers, 0 - 5; see Appendix A.) 
As in the ABSOLUTE READ, the special case of writing a single string variable holding 
exactly 512 bytes (its DIM'ed length) has substantial speed advantages which make it 
advisable in most cases. 
Examples: 
WRITE (ABSOLUTE=1,REC=319) A$ 
WRITE (IOLIST=WList35,FORMAT=Form35$,ERL=WriteErr,R EC=J*U,ABSOLUTE=1) 
WRITE (ABSOLUTE=1,REC=Indexer,IOLIST=List) J,Non$ 
2.12.3 DELETE Statements 


definition: DELETE statement 
DELETE (LFN=numerie expression[ ,ERL=statement label) 


A DELETE statement consists of the reserved word DELETE followed by an LFN group 
enclosed in parens, optionally followed by a comma and an ERL group. 
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DELETE statements delete the last ISAM record read. The numeric expression in the 
LFN (logical file number) group specifies which file is affected. The ERL (error line) 
group, if used, sets an I/O error trap, transferring control to the line designated by 
the statement label if an I/O error occurs during execution of this statement. 


To delete an ISAM file record, the file must be open in a mode allowing write (set 
in the open statement) and the record to be deleted must be locked. To lock a record, 
the LOCK control in the READ statement must be set at 1 ‘the default value). No 
other operations on that file can be done between the locking READ statement and 
the DELETE statement or the record will be unlocked and an I/O error will result. 


Examples: 


D1: DELETE (LFN=3) 

D2: DELETE (LFN=5,ERL=D.ER) 

D3: DELETE (LFN=R.num,ERL=ETest) 
D4: DELETE (ERL=Back,LFN=N*S+3) 


Example D1 deletes the last record read in file 3. 

Example D2 deletes the last record read in file 5, with an error trap set for I/O 
errors. 

Example D3 uses a variable to indicate LFN, sets an error trap. 

Example D4 uses an expression to indicate LFN, sets an error trap. 


2.12.4 UNLOCK Statements 


definition: UNLOCK statement 
UNLOCK (LFN=numeric expression [,ERL=statement label] ) 


An UNLOCK statement consists of the reserved word UNLOCK followed by an LFN 
group and an optional ERL group, enclosed in parens. 


UNLOCK statements are used to unlock records in random or ISAM files. The LFN 
group designates which file; since only one record per file per user can be locked, the 
LFN is all that is needed to identify the record. The optional ERL group ean be used 
to set an error trap for I/O errors during execution of the statement. 


Records in random or ISAM files are locked by being READ with the LOCK option 
set to 1 (the default value). Records in ISAM files must be locked to be rewritten 
or deleted. If an examination of the data after a READ indicates that the record is 
not to be rewritten, or deleted, an UNLOCK statement can be used to release the 
lock on the record. Any other operation on that file also releases the lock, however. 


An UNLOCK statement issued to a file which contains no locked reeords has no effect 
and is not an error. 
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Examples: 

U1: UNLOCK (LFN=8) ; 
U2: UNLOCK (ERL=Check,LFN=F.number) 
U3: UNLOCK (LFN=T*I/N+7,ERL=ETest) 


Example U1 unlocks file 8. 

Example U2 uses a variable to designate LFN, sets an error trap. 
Example U3 uses an expression to designate LFN, sets an error trap. 
2.12.5 REWIND Statements 


definition: REWIND statement 


REWIND (LFN=numeric expression[,ERL=statement label ]) 


A REWIND statement consists of the reserved word REWIND followed by a control 
list enclosed in parens. The control list consists of an LFN group, optionally followed 
by a comma and an ERL group. 


REWIND statements are used to return to the logical beginning-of-information in 
sequential and ISAM files (to reposition the READ pointer, in other words). The LFN 

co (logical file number) group specifies which (necessarily open) file is to be rewound. 
The ERL (error line) group, if used, specifies a line to receive control if an I/O error 
occurs during execution of this statement. 


Examples: 


Ri: REWIND (LFN=12) 
R2: REWIND (LFN=TaxFile,ERL=ErTest) 
R3: REWIND (ERL=CheckR3,LFN=File+CheckSum) 


Example R1 rewinds file 12. 
Example R2 uses a variable to set LFN, sets an error trap. 
Example R3 uses an expression to set LFN, sets an error trap. 


2.12.6 ISAM Use In Sorts 


Because the keys (index items) to ISAM files are kept in ASCII collation order (by 
their character values on the ASCII chart, Table 2-8, with XYZ(blank) ordered just 
before XYZ!, and so on), ISAM files are extremely useful in sorting data in a variety 
of ways. 


The basic method is to create a cross-reference ISAM file. If the data can be contained 
in 2 to 24 characters, the data will be its own key. Likewise, if the data is contained 
in another ISAM file, the key of the new file will contain the key to the old file, so 
that the new file can reference the old file's data master, rather than duplicating file 


co space. 


2-153 


2.12.6 ISAM Use In Sorts LANGUAGE 


TITLE "EXAMPLE: Sequential Sort" 


H Sort sequential file "SEQ" by record position 53:5. 
: Assume 500 written records 100 bytes long, 
' each written as a single character string. 


:declare 
Dim Record$(100) fixed ‘holds records 
Dim Scrkey#(5) based iscratch key 
Dim File#(1@) ;input filename 
Dim SFile% (10) iscratch file name 
iinitislize 
Record$=" " iblank fill 
Base Scrkey# at Record$(1) iname Record$(175) ScrKkey$ 
File$="SEQ" }input sequential file name 
SF iles="SCRATCH" ‘sort scratch file name 
Bell$=CHRS (7) irings bell: Beep! 
iopen; allocate files 
OSeq: }open sequential input file 
OPEN (LFN=1,FILE=File%,ERL=OSeqCheck ) 
AScr: tallocate ISAM scratch file 


ALLOCATE (LFN=2,FILE=SFile#,ERL=AScrCheck » 

. RECFMT="F" ,ORG="I" -NREC=500 ,-RECLEN=100 -KEYLEN=5 , 

“ UNIT=1,IUNIT=1) 

OScrs ropen ISAM scratch file 
OPEN (LFN=2Z2,FILE=SFile#,OPT=14,0RG="I", 

* UNIT=1,IUNIT=1,ERL=OScrCheck ) 


iread sequential file, write ISAM scratch file 

Loopli 2 

READ (LFN=1 ,-EOF=EndLoop1,ERL=LoopiCheck) Records 

Wit WRITE (LFN=2,KEY=ScrkKey#,ERL=WiCheck) Records 
Goto Loopl 


;close sequential file, rewind ISAM file 
EndLoopt: 
CLOSE (LFN=1-ERL=EndLoopiCheck) 
REWIND (LFN=2) 


}open printer, print sorted file 
OPtrsOPEN (LFN=@,ERL=OPtrCheck ) 


Loop2: 

READ (LFN=2,KEY=ScrKey$-,EOr=Endloop2 -ERL=Loop2Chneck ) 
° Recorcs 
W2: WRITE (LFN=@-,ERL=W2Check) "Key = ",ScrKey$,LF$,CR$, 
° "Pecord = ",Record$,LFs 

Goto Loop2 


‘close printer, close delete ISAM scratch file, end action area 
Endloop2: 

CLOSE (LFN=0,ERL=EndLoop2tneck ) 
CScriClLOSE (LFN=2;OPT=1,ERL=CScrCheck ) 

STOP 


2-154 


LANGUAGE 


2.12.6 ISAM Use In Sorts 


OSeqCheck 


1 1 PERe DS 
' CERUEG*DS 


ee oD Ee SB 
aa eB ut 


ERROR TRAPS 


Poe ELAR TEER HR ST EE SPOHHCVRS CPE CPS CP EH EP ET e Ee wis § 
fereevpres PP 28 8 | a LPKRAT ED EPH ERD ERASER ae Psat © eT Ee 


rerror on sequential open 


E=IOERR igsave error number 
OSLoop? 'give message with bell 

Print "ERROR",E," during attempt to open file ",Files, 
. Bells 

Input (PROMPT="Insert disk bearing "&Files&" in unit O"& 
7 “and type ""G"", or type ""S"" to stop: ") Tests 

If Test$="S" then STOP rquit 

If Test$ NE "G" then ibad input 

Print Bell iBeep ! 


AScrCheck * 


Geto OSLoop 
Endif 
Goto OSeq 


itry again 
igo back and continue 


‘error on ISAM allocate 


E=IOERR iSave error number 

Tf E=7? then ‘duplicate file name 
OPEN (LFN=2,FILE=SFile$,OPT=14,0RG="I",UNIT=1,TIUNIT=1) 
CLOSE (LFN=2,O0PT=1) iepen and close delete it 
Goto AScr 1go back and allocate it 

Endif 


iLFN in use 
iclose whatever it is 
igo allocate scratch 


If E=11 then 
CLOSE (LFN=2) 
Goto AScr 


. Endif 


ASLoops 


A 


Print "ERROR",E," during attempt to allocate ISAM scratch", 
" file." ,Bells 'give message, ring bell 


Input (PROMPT="Insert scratch disk in unit 1 and type"& 
" "™"G'" to continue, or type ""S"" to stop: ") Tests 
If Test$="S" then STOP rquit 
If Test NE "G" then tbad input: 
Print Bells i Beep! 


Goto ASLoop 
Endif 
Goto AScr 


‘try again 


igo back and try allocate 


OScrCheck : 
E=TOERR 
PRINT Bells. 


» 


‘error on ISAM open 
}Save error number 


"ERROR",E," during attempt to open scratch file", 


° "on unit 1. "&LFEt&CRee 

e "Sort of sequential file "Filet." aborted." 
CLOSE (LFN=1) iclese input file 
STOR rquit 
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OO 


LoopiChecki 
E=IOERR 
LiCheckLoop: 


INPUT 


A 


a 


a 


If Tests="S" 


(PROMPT=Bel 1$& 


"ERROR "BE&" during reading 
LFS&CRS& 
"Type ""G"" to continue, 


then 


CLOSE (LFN=1) 
CLOSE (LFN=2,0PT=1) 
STOP 


Endif 


If 


Tests NE "G" 
Print Bells 
Goto LiCheckLoop 


then 


Endif 
Goto EndLoopl 


WiCheck : 
E=] 
WiLoop: 


INPUT 


a 
a 


a 


If 


OERR 


(PROMPT=Bel 1$& 

"ERROR "SER" during write to 
LFS&CRd& 

"Type ""G"" to continue, 
Test$="S" then 

CLOSE (LFN=1) 

CLOSE (LFN=2,0PT=1) 

STOP 


” “Ss 


Endif 


If 


Tests NE "G" 
Print Bells 
Goto WiLoop 


then 


Endif 
Goto EndLoopi 


EndLoop! 


Check? 


E=IOERR 


ELiCheck 
INPUT 


a 
Aa 


A 


If 


Loop: 
(PROMPT=Bel 1$& 


im "go ” 


rerror during ist read 
!Save error number 


OF input files "SF i] 2eb&", "%, 


to stop: ") Tests 


}close input file 
‘close delete ISAM scratch 
rquit 


rbad input 
iBeep! 
iback for better input 


‘continue: use as much 
‘as is in scratch file 


‘error during ISAM write 
{save error number 


ISAM scratch file."& 


"to stop: ") Tests 
iclose input file 
‘close delete scratch 


iquit 


tbad input 
‘Beep ! 
try for better input 


‘continue: use as much 
‘as is in scratch file 


tclose of input file fails 
‘save error number 


"ERROR "BE&" during attempt to close input file "EF i Lede 


" "SLFSeCRo& 
"Type ""G"" to continue, ung 
Tests="5" then 


CLOSE (LFN=2,OPT=1) 
STOP 

Endif 

If Test® NE "G" then 
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!quit 


‘bad input 
iBeep! 
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Enidif 
REWIND (LFN=2) ‘set scratch to continue 
Gote OFtr ‘comtinue: use as much =s 
‘is in scratch “ile 
OPtrCheck é 1error Gm printer open 
E=IOERR isave error number 
OPtrLloop: 
INPUT (PROMPT=Bel1sé: 
* "ERROR "SE&" during attempt to open printer.”%& 
in LF S&CRSE: 
- "Type ""G"" to continue, ""S"" to step: ") Tasts 
Tf Test$="S" then 
CLOSE (LFN=2,O0PT=i1) ‘Close delete scratcth fila 
STOF iquit 
Endif 
Tf Test NE "G" then tbad input 
Print Bells /Beep ! 
Goto OPtrLoop itry for good input 
Endif 
Goto OPtr itry again to open printer 
Loop2Check: . ferror on "INEXT" read 
E=IOERR }$ave error number 


Print Bell#,"ERROR",E," during attempt to read ", 


. "ISAM scratch file on unit 1.",LFS,-CRS, 

° "Sort of sequential file ",File#," aborted at this "; 

a "point." 
Goto EndLoop2 ;quit 

W2Check § rerror on write to printer 
E=IOERR 1$ave error number 


Print Bell$,"ERROR",E," during write to printer.”, 
. LFS, CR, 


"This aborts sort of sequential file ",File$,".” 


> 


Goto EndLoop2 iquit 

EndLoop2Check : ferror on close of printer 
E=IOERR iSave error number 
Print Bell#,"ERROR",E," during attempt to close printer.” 
Goto CScr 'quit 

CScrCheck: rerror on scratch close 
E=TOERR 'Save error number 


Print Bell%#,"ERROR"-E," during attempt to close delete”, 
" scratch sorting file on unit 1.” 
END rquit 
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TITLE “EXAMPLE: ISAM Cross-Reference Sort” 


H Sort file "ISAM" by record position 5:5. 
' Assume S@O recerds 100 bytes long, 10 byte beys. 


ideclare 
Dim Record$(100) fixed ihoids records 
Dim FirstKey$(19) based roriginal file keys 
Dim SecondKey$(i5) fixed icross reference file key 
Din KeyHolder$(5) based isought field in Records 


iinitislize 
Record$=" " 
Base KeyHolder$ at Records(5) 
SecondkKey#=Records 
Base FirstKey$ at SecondKey$(6) 
X$=" "' idummy value for records 


Because FirstKey$ is based on the last 190 characters 

of SecondKey$, as FirstKey# is read into, SecondKey$ 
receives its data in positions & through 15. KeyHolder$ 
is based on the desired field in Record$, so it is then 
equated to the first 5 characters of SecondKey$. The new 
key field is concatenated in this way with the old key. 
The old key is used to ensure uniqueness of the new keys. 


H (This example will omit error traps for easier resding.)? 


tallocate scratch file, open printer and files 
ALLOCATE (LFN=1,FILE="SCRATCH” -RECFMT="F" -ORG="I", 
. NREC=500 ,-RECLEN=100 -KEYLEN=15,UNIT=1,IUNIT=1) 
OPEN (LFN=@) 
OPEN (LFN=1,/FILE="ISAM" -ORG="I",OPT=6) 
OPEN (LFN=3,-FILE="SCRATCH” ,ORG="I"-OPT=14,UNIT=1,IUNIT=1) 


‘create new file 
ReadLoop: 
READ (LFN=1,KEY=FirstKey$,EOF=EndReadLoop) Records 
Secondkey# (155) =KeyHoldert 
WRITE (LFN=3-KEY=SecondKey#) X$ 
Goto ReadLoop 


' Since FirstKey# is the last two-thirds of SecondKey$, 

H and KeyHolder$ is the 5 through 9th characters of Records, 
' the read statement and the assignment statement create 
anew key for the cross-reference file. The new key is 

' unique Secause the old key is (allowing sorts oy ZIP 

' code, for instance). X$ 18 8 dummy: the data 

will be cross-referenced from the original file by 

H separating the old key from the new one, 
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EndReadloop: 
REWIND (LFN=3) 


now cross-reference and dump on printer 

KRefLoopt 
READ (LFN=3,KEY=SecondKey$-EOF=EndxXRefLoop) X% 
READ (LFN=1,KEY=FirstKey$ -MODE="F") Records 
WRITE (LFN=@) "New key = ",SecondKey$,LF%,CR$, 

7 "Old key = ",FirstKey$-/LF%-,CR$, 


* "Record = ",Record$,LFS 
Goto XRefloop 


The first read statement sequentially "INEXTs" 

by key order through the cross-reference scratch file. 

The original file is then read "randomly", by 

key value (FirstKey# is the last two-thirds of SecondKey®) - 
and the keys and record are printed. 


‘close and quit 


EndxRefloop: 
CLOSE (LFN=0) iclose printer 
CLOSE (LFN=1) iclose input file 
CLOSE (LFN=3,0PT=1) iclose delete scratch 
END 
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TETLE "EXAMPLE: ISAM Sort Ey Partial Key” 
i Find a record or records in an ISAM file 
' by @ partial key (also known as a 
H “generic search"). For example; find 
H all employees whose last name begins 
' with JON. 
! Assume 50@ records, 19@ byte records, 
H 15 byte key (employee’s name, last name first). 
H Records are a single string. 
H (Again, error traps are omitted for easier reading.) 
Dim Record$(190) fixed tholds records 
Dim FirstKey$(15) fixed tholds keys 
Dim PartKey#(3) fixed ipartial key holder 
OPEN (LFN=1,;FILE="EMFILE” ,OPT=6,ORG="I") 
NameIn: Input (PROMPT="Employee name? ") FirstKey$ 
READ (LFN=1-MODE="R",KEY=FirstKey$,ERL=Partial) Records 
' other processing would intervene here 
H for normal updates 
Partial :PartKey$=FirstKeys ‘put key in holder 
Print CS$(1),"Records which match your input include:" 
PLoop: READ (LFN=1,KEY=FirstKey$,EOF=EndPLoop) Record 
If FirstKey$(1;3)=PartKeys then 
Print (Carr=@) CP$(1,5),ES%,"Employee name: ", 
* FirstKey$ 
Print (Carr=0) CP#(1,7),"Record: ",Record?#, 
* CP$(1,16),"Type any key to continue” 
Hold: TF KEYIN#H=""" then goto Hold 
Else 
Goto EndPLoop 
Endif 
Goto PLoop 
EndPLoop? 


A 
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Print CS®(1),"End of names beginning with “-PartKey$, 
Goto Nameltn 
END 
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FILES 
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DX-85M System Utility Usage 
Syntax 
Use 


EDIT[/unit] [*] filenamel/unit][,filename2 [/unit]] [1] [o] [L][u] 
invokes editor, creates and edits files; 

/unit indicates disk unit; 

EDIT/1 indicates EDIT program from unit 1; 
optional * uses large font on screen; 

if optional filenamel not used, 
filename/unit will create file names 

on disk unit designated; if filename2 

used, filename2 will be name of new file 
/unit after filenamel indicates source 

file location and in filename2/unit, 

unit designates output destination; 

all unit's default to unit 0 


FILES [/unit] [unit ] [specifier [s,]] 

reads file directory entries, deletes, 

renames and dates files, changes file 

attribute designation and write-protect 

status; /unit designates disk unit containing 
FILES program; unit designates unit containing 
disk directory to be read; both unit's default 
to disk unit 0; specifier(s) 

(filenames or characters with * or ? "wild cards") 
designate file entries to be read; 

see DX-85M FILES COMMANDS table 


DSCAN [/unit] [unit ] 

seans unit for hard errors; 
optional /unit designates 

disk unit containing program; 
optional unit indicates disk unit 
containing disk to be scanned; 
both default to unit 0 


COPY [/unit ][specifier {s,]][/unit] TO [specifier [s,]][/unit] [1] [O][L][U] 
copies files specified; optional /unit's designate location o 

COPY program, files to be copied and target disk, respectively 

(all default to unit 0); specifiers are file names or partial 

names with * (matches any string) or ? (matches exactly one character), 
optionally followed by /TFP where T is replaced by type designation, 

F by format and P by write-protect designator (*skips position, 

final - blanks write-protect column); second specifier list 

changed file names; I clears target disk before copying, O 

clears file to be copied from target disk before making copy; 

L will copy the diskette label, U will only copy if the file already exists; 
at least one specifier in /unit must precede and follow the TO. 


DX-85M System Utility Usage APPENDIX A 


FORMAT 


RUN/RUNB 


COMPILE 


compiler para- 


meter list 


BATCH 


BDUMP 
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DX-85M System Utility Usage (cont'd.) 


FORMAT [/unit | 

formats disk for system use; 
optional /unit designates 
disk unit containing program 
(defaults to unit 0) 


RUN [/unit] [control filename [/unit ]] 
run-time monitor; optional control 

file specifies partitioning and 

common area for multi-tasking; default 

is single user mode; /unit designates 

disk unit(s); default is unit 0; 

RUN/RUNB command prompt is * (see RUN 
Commands table) 


COMPILE [/unit] input filename[/unit][ compiler parameter list ] 


[OBJECT=flenamel /unit SID RA RY efits or_*[/unit]] 
[ OPTIONS=option string ][LIBRARY = filename [/unit 
[OBJ=filename[/unit]][LIST=filename or *[/unit | 
‘[OPTION=option string ][LIB = filename [ /unit 


[O=filenamel /unit] ][ L=filename or *[/unit ] 


A(OPT=option string ][LIB = filename [/unit]] 


input filename is the source code file; 
/unit designates disk unit (default is unit 0); 
object and list filenames designate object code 
file and listing file names; object default 
is to add .OBJ to input filename at first . 
or at end; listing default is to list on printer; 
=* displays listing on video (/unit not allowed 
if L=*); option string is one or more of the 
control characters PSNECKX (see COMPILE Compiler 
Options table); library file may be BASIC.LIB (the standard library file) 
or another, user-created library file. 


BATCH [/unit ] input filename [/unit] [output filename [/unit}] 

allows unattended use of the F-85; all keyboard input is replaced by 
data from the input file; if optional output file is used, all screen displays 
are recorded there; returns to : prompt when first input request is 
reached after input file is emptied 


BDUMP [/unit ] unit startblock [endblock] [ L ] 

dumps disk hex code and ASCII translation on video or printer; /unit 
designates unit bearing BDUMP; unit designates disk unit to be read; 
startblock is number of first block to be read; endblock (if used) designates 
last block to be read; (default is to read until CODE ESC is pressed); 
optional L designates printer output; default is video display 
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EDIT CONTROLS, COMMANDS AND ERROR MESSAGES 


EDIT CONTROLS, COMMANDS AND ERROR MESSAGES 


Edit Commands (to $ prompt) 


E 
End successful edit, write output file and 
close truncate. 


A 
Abort edit, delete output file. 


Pfilename[/unit],strin 

Position named file (from unit if not on 
unit 0) at the first instance of string; 
RETURN brings back file being edited, 
(down arrow) scrolls through file being 
searched; may be used on input file or any 
other file. 


Gfilename[ /unit] ynumber1 ,number2 

Get line from physical line number1 through 
number2 from file filename (on unit if not 
on unit 0), insert in file being edited just 
after last line on screen with last new line 
at bottom of screen. 


TC Clear tab stops (stop at 6 columns, 
then every 3 to follow, is automatic 
on entering EDIT). 


TA 
Assembler tab: clear tabs, set new stops 
at columns 9, 15 and 30. 


Fstring 

Find the first instance of the search string 
in the input file, position that line at bot- 
tom of screen; leave rest of screen blank. 


Sstring 

Search for string at left end of lines 
below screen (used for fast searches for 
line labels); position that line at bottom 
of blank screen. 


R/string1/string2[/A ] 

Replace stringl with string2 from line 
just below screen to end of file; optional 
/A at end of command orders all replace- 
ments automatically; if A is not used, 
operator must give a Y to prompt for 
each line to replace: ESC (abort, only in 
R.command) at prompt ends the entire 
EDIT and leaves the file as it was 
previous to the EDIT run. 


Lnumber 

Move input file to physical line number; 
line number will be at the bottom of a 
blank sereen. 


Knumber : 
Delete the next number of lines, starting 
at the line just below the screen. 


Tnumber 
Sets tabs at column number and every 


number thereafter, where number is an 


integer between 1 and 9; (T3 sets a tab 
at columns 3,6,9,12,15 and so on). 


U 

Upper case toggle: toggles the reverse 
alpha shift of the keyboard; used for the 
first time, it results in a normal type- 
writer shift for alphabet characters; used 
again alpha shift is reversed. 


EDIT begins in normal editing mode, with the first line of the input file just below 


the sereen. 


The (down arrow) key will seroll lines onto the screen (and off the top, 


to the output file, when the screen is full) if it is at the bottom left corner of the 


screen. 


To enter command mode, press the ESC key. The $ prompt will appear at 
the lower left corner with the cursor beside it. 


Enter the command as shown above 


and press RETURN, or use CODE C, and EDIT returns to normal editing mode. 
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EDIT CONTROLS, COMMANDS AND ERROR MESSAGES (cont'd.) 


EDIT Control Keys 


(left arrow) 
Move cursor left. 


(right arrow) 
Move cursor right. 


(up arrow) 
Move cursor up. 


(down arrow) 
Move cursor down; if at lower left corner 
of screen, scroll on new line. 


CODE (down arrow) 
Move cursor to lower left corner of sereen 
("home"). 


ESC 
Enter command mode (give $ prompt at 
lower left with cursor alongside). 


EDIT Error Messages 


EOF ON. INPUT FILE 
End of file reached on the input file (L,F, 
S and K commands). 


EOF ON GET FILE 
End of file reached during G command. 


EOF ON POS FILE 
End of file reached during P command. 


PARAMETER ERROR 
Error during EDIT invocation, or in the syn- 
tax of a command. 


INVALID FILENAME 


File name is too long, or contains illegal 
characters, or is otherwise invalid. 


NO INPUT FILE 
Input iile not found on disk unit specified. 
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DEL 
Delete character at cursor. 


CAN or CODE X 
Cancel characters on cursor line; if cur- 
sor is at left end, cancel line too. 


CODE Z 
Add blank line at cursor, move line at 
cursor and above upward. 


CODE T 
Set tab stop at cursor. 


TAB 
Move cursor to next tab stop to right. 


CODE C 
Cancel EDIT command mode, 
normal editing mode. 


resume 


OUTPUT FILE IS WRITE-PROTECTED 
Specified output file is marked as write- 
protected in its $DIRECTORY entry. 


OPEN ERROR ON OUTUT FILE 

Error occurs during attempt to open out- 
put file: EDIT.TMP temporary output file 
may be left on diskette. 


DISK READ ERROR 
Error during attempt to read file. 


DISK WRITE ERROR 
Error during attempt to write file. 


CLOSE ERROR ON INPUT FILE 
Error during attempt to close input file. 


CLOSE ERROR ON OUTPUT FILE 
Error during attempt to close truncate 
output file. 
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EDIT CONTROLS, COMMANDS AND ERROR MESSAGES (cont'd.) 


INVALID LINE NUMBER 

Line number specified is not an integer, 
is out of range, or is previous to present 
position (L command). 


INVALID NUMBER 

Number of lines is not an integer, is out 
of range, or otherwise illegal (K com- 
mand). 


INVALID LINE NBR 
G (Get) command physical line number is 
not legal. 


OPEN ERROR ON GET FILE 

Error during attempt to open file for 
insertion of material with the G (Get) 
command or the P (Position) command. 


INVALID STRING 
Search string is not legal (P command). 


INVALID COMMAND 

Command is not legal command, is syn- 
tactically illegal, or is otherwise 
illformed. 
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DX-85M COMPILE Compiler Options 


Option Meaning 
Symbol 
P print only error lines; default is print all source lines 
Ss suppress printing of symbol table: default is print symbol 
table 
Cc print object code interspersed with source code listing; 


default is no object code printed. 


E error search only: suppress creation of object code, merely 
sean source code for errors; default is generate object code 


N no printing: suppress printing of source lines and symbol 
table information; print error lines only, display memory use 
and number of errors on video 

K compressed font: use small font for listing 


X cross-reference: generate a symbol cross-reference listing 


includes statement labels in the symbol table listing. 
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DX-85M RUN/RUNB Commands 


Command Syntax 
Use 
load and go * filename [/unit 


filename is object code file; 
/unit designates disk unit (default is unit 0); 
RUN loads and runs the object program specified; 


LOAD * LO filename[/unit] 
loads object file specified from 
unit specified (default is disk unit 0) 


RUN * RU 
runs currently loaded program from 
its start 

GO * GO 


runs currently loaded program from 
the current position (from start if 
program has not yet been run) 


QUIT * QU 
leave RUN and return to system 
command level (: prompt); not 
legal in multi-tasking mode 


BREAKPOINT * BR [location number ] 
sets breakpoint in currently loaded 
program at location specified (location 
number is a hexidecimal number from the 
compiler listing); if location number 
not given, clears all breakpoints; 
up to 8 breakpoints can be set 


DISPLAY * DI location number [(inte = 
displays the value of the variable 
or array specified; location number 
is a hexidecimal number, the descriptor 
location taken from the compiler listing 
symbol table; optional (integer) designates 
which value of a numeric array or two-dimensional 
string array 


* is the RUN/RUNB command prompt 
[] brackets mark optional expressions 
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Command 


specifier 


LIST 


UNIT 


DELETE 


RENAME 


ATTRIBUTE 


SPACE 


DX-85M FILES Commands 


Syntax 
Use 


filename [,specifier[s, ] ] 

[ wildeard[s ]][printable [s] ][ wildeard[s ]][..][/attributes ][,specifier[s, ] ] 
specifies file to be acted upon by FILES 

wildeards are *, which matches anything, and ?, which 

matches exactly one printable character; / followed by one 

to three characters indicating attributes (formed as in the alpha 

list of the ATTRIBUTE command, below) selects files by their Type, 
Format and write-Protect status 


L[specifier[s,]] [P] 

lists file directory entries specified 

on VDU (optional P lists on printer 

as well); printables after L are | 

used for memory aids only; if specifier 
not used, lists all files on directory 


U unit 

changes disk directory being read; 
unit designates unit to be read; 
printables are memory aids only 


D specifier[s,] [V] 

deletes file(s) specified: 
optional V requires file by file 
verification; printables are used 
for memory aid only 


R specifierl specifier2 [,specifier3 specifier4... ] 

renames files; file(s) designated by specifierl are 

renamed as designated by specifier2; pairs of specifiers 
are separated by commas; printables are memory aids only 


A specifier[s,] alphal[ alpha2[ alpha3 ]] 


changes type, format and write-protect designators; 
alphal designates type; alpha2 record format; 

alpha3 write protection status; alphal and alpha2 
can be any alphabetic character or a * (which will 
skip that position); alpha3 can be any alphabetic 

or a - (which blanks write-protect column in listing); 
printables are memory aids only 


s 

displays space utilization on 
disk; printables are memory aids 
only 
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DATE 


EXIT 


DX-85M FILES Commands (cont'd.) 


DA specifier[s,]6 printables 


dates files specified with 6-character 
string; any six printable characters 
(including blanks) may be used; optional 
printables are memory aids only 


E 


ends FILES program, 


returns to system command level 


[] brackets mark optional expressions 


Files specifiers are used within FILES commands (and are somewhat 


different from specifiers in COPY utility use). 


only be entered after the FILES' command prompt: 
ENTER: LIST,UNIT, DELETE,RENAME,ATTRIBUTE,SPACE,DATE,EXIT 


FILES commands may 
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_. DPATCH Control Keys, Commands And Error Messages 


Control Keys 


(down arrow) 
If cursor is at left corner, advance to 
next line in block. 


(up arrow) 
If cursor is at left corner, scroll back- 
wards (move last line on screen off 
screen, second from last line to bottom 
of screen). 


ESC 
Enter command mode ($ prompt) 


(any other input) 
Marks changes to field above it; 'X 
(single quote, single character) inserts 
the character's ASCI code; NN, where 
N is a hexidecimal digit, inserts that 
hexidecimal code. 


Commands 


(right arrow) 


Move cursor to next field on right. 


(left arrow) 
Move cursor to next field on left. 


RETURN 
Make insertions as marked.+ 


DEL 
Delete character to cursor's left. 


CAN 
Cancel line, move cursor to left corner. 


(illegal codes or input) 
Mlegal change markes cause the field 


to be set to null (00) when RETURN ° 


orders change. 


(DPATCH must be in command mode — $ orompt) 
4 


‘E 
End session, write current block’ to disk. 


N 


Next block: write current block to disk, 
get next block in numeric order (if you 
have block X, the N command will read 


the block X+1). 


Fstring 


Find string (one or more characters) in the 
off-screen portion of the current blocks, 
position first line containing string at the 


bottom of the screen. 


F 


Find again: repeat last F command on rest 


of current block. 


A 
Abort session, do not write current 
block to disk. 


B 
Block beginning: return to the top of 
the current block. 


Bnumber 

Get block number from disk, write 
current block to disk. number is 1 to 
5 digit decimal sector number. 


H HEX VALUE 


Hex value = 2 digit hex number. Hex 
search finds a string (one or more 
characters) in the off sereen portion of 
the current blocks, position first line 
containing string at bottom of screen. 


DPATCH, DX-85M Commands 
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DPATCH Control Keys, Commands And Error Messages (Cont'd) 


Error Messages 
BAD COMMAND BAD CHANGE: item? 


Command syntax is illegal. 


or otherwise illegal. 


STRING NOT FOUND 
F command, end of block reached, but END OF BLOCK 


string searched for is not there. 


Commands 


The change item is in the wrong place 


Down arrow when the last line of the 


block is at the bottom of the screen 
READ ERROR: STATUS = number returns this message. 
If a disk error is encountered, this message 

is issued. number is the STAR BASIC error 

number (see Appendix D). 


DX-85M Commands 


Syntax 
Use 


HEX 


DUMP 


SET 


LOAD 


BREAKPOINT 
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H address value [ value[... ]] 
alters value s starting at 
address 


D address [ address ] 

displays memory contents on video 
from first address to last; if last 
address not specified, dumps 2 bytes 
starting at address specified; 

ESC (escape) key terminates dump early 


S alphabetic value 
sets register to specified value 


L filename 
loads program from diskette memory 


BL address ] 

with option, sets breakpoint in 
current program at line specified; 
without option, clears all breakpoints 


G [parameters ] 


Go: runs program loaded in memory 
from current point; option supplies 
program parameters (if needed) 


[] brackets mark optional expressions 
all addresses and values are hexidecimal 
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DX-85M Hexidecimal To Decimal Conversion 


Converts two-digit hexidecimal numbers to decimal. 
Most significant digit is on the left (i.e., BF=191). 


Hexidecimal-Binary-Decimal Conversion 
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STAR BASIC Syntax: Characters, Elements, Operators 


Item 


STAR BASIC characters alphanumerics 


alphabetics 


numerics 
period 
symbols 


statement label 


numeric constant 


string constant 
numeric variable 
string variable 
numeric array 
string array 


functions 


grouping operators 
mathematic operators 


addition 
subtraction 
multiplication 
division 
remaindering 


concatenation 
negation 
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Syntax 


alphabetics 
numerics 
_ period 

sym 


upper case: 


lower case: 


ABCDEFGHIJKLMNOPQRSTUVWXYZ 
abedefghijklmnopqrstuvwxyz 


0123456789 


(blank) "$ &<> =+-* /\(),.3 244 


numeric [s][:] 
alphabetic [up _to 31 alphanumerics }: 


[+][numerice[s]][fraction ][Etnumeriec [s] 

"(printable ASCII characters ]" 

alphabetic[ up to 14 alphanumerics ] 

alphabetic[ up to 14 alphanumerics ]$ 

numeric variable name(subscript[ ,subscript ]) 

string variable name (subscript[ subscript ][;subscript ]) 

string variable name (starting position[,which string ][;length }) 


utility functions (see table) 
1/O funetions (see table) 


user-defined functions (see FUN statement) 


[expression operator] (expression) [ operator expression ] 


expressiontexpression 
expression-expression 
expression* expression 
expression/expression 
expression\ expression 
expression& expression 

expression 
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cy STAR BASIC Syntax: Operators, Expressions 


Item Syntax 


continuation operator used in leftmost column only, continues a 


A statement over two or more lines 
numeric element numeric constant 


numeric variable 
numeric array 


numerie function 


string element string constant 
string variable 
string array 
string function 
mathematical numeric element mathematical operator mathematical expression 
expression string element mathematical operator mathematical expression 
relational mathematical expression relational operator mathematical expression 
expression 
conditional [NOT] relational expression binary logical operator conditional ex- 
a expression A pression 
element numeric or string element 
variable numerie or string variable 
array numeric or string array 
variable reference numeric or string array reference or numeric or string variable 
function numeric or string function 
expression mathematical expression 
numeric expression mathematical expression with numeric value 
string expression mathematical expression with string value 
filename "alphabetic up to 9 printable characters " 
variable list variable[,variable[ ,variable[ ,... ]]] 
expression list expression[ ,expression[ ,expression[ ,... ] ]] 
statement label list statement _label[,statement_labell statement label [,... ]]] 


used to indicate repetition of expression form, primarily in lists 


word underlined words are syntactic variables, replaced by the 
indicated elements in actual expressions 


€" [ ] square brackets indicate optional expressions in definitions 
(they do not appear in STAR BASIC outside of string literals) 
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STAR BASIC Syntax: Operators 


Item 


STAR BASIC Syntax: Operators 
Syntax 


APPENDIX A 


relational operators 


is equal to 


is not equal to 


is greater than 


greater or equals 


is less than 


less or equals 


logical operators 
AND 


OR 

NOT 

operator precedence 
first 

second 

third 

fourth 

fifth 

sixth 

seventh 


eighth 
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expression=expression 
expression EQ expression 


expression> <expression 
expression> <expression 
expression NE expression 


expression> expression 
expression GT expression 


expression>=expression 
expression=> expression 
expression GE expression 


expression <expression 
expression LT expression 


expression <=expression 
expression=<expression 
expression LE expression 


conditional expression AND conditional expression 
conditional expression OR conditional expression 


NOT conditional expression 


grouping 

negation 
multiplication,division,re mainder ing 
addition,subtraction 

concatenation 

relational 

logical negation 

logical conjunction,disjunction 


where precedence is equal, expressions 
are evaluated left to right 


EQ NE GT GE LT LE 
NOT 


AND OR 
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STAR BASIC Syntax: Comments Assignment, Declarative, 
Loop/conditional Statements 


Item Syntax 


Comment statements 
REM REM STAR BASIC characters 


statement REM STAR BASIC characters 
"STAR BASIC characters 

statement ' STAR BASIC characters 
REMARK STAR BASIC characters 


statement REMARK STAR BASIC characters 


TITLE TITLE "quoted literal" 

EJECT EJECT 

LIST LIST [ON J[OFF] 

Assignment statements 

LET [LET ] variable reference=expression 

BASE BASE based array name AT variable reference 
— statements 

COMMON COMMON variable name [variable Name [y+ J] 
DIM DIM variable name(integer Zinteger])[dim_options][,... ] 
dim_options [ BASED ][ FIXED] 

DATA DATA constant] ,... ] 

IOLIST statement label IOLIST expression [ ,expression ] ,... ]] 
STOP STOP 

END END 


Loop/conditional statements 


FOR FOR numeric variable=numerie expression TO 
Anumerie expression [STEP numeric expression ] 

NEXT NEXT numeric variable 

IF-THEN IF conditional expression THEN statement 
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STAR BASIC Syntax 


Item 


IF-TH EN-ELSE-EN DIF IF conditional expression THEN 


Transfer/subroutine statements 


GOTO 


GOSUB 
RETURN 


ON GOTO 


ON GOSUB 


CALL 


subroutine name 


parameter list 
SUB 


argument list 
FUN 


function name 


EXIT 


CALL CHAIN 


STAR BASIC Syntax: Loop/conditional Statements, a 


more statements, as above ] 
[ELSE 


APPENDIX A 


Transfer/subroutine Statements 


Syntax 


| statement : 
statement 


[more statements, as above ] 
ENDIF 


GOTO statement label 
GO TO statement label 


GOSUB statement label 
RETURN 


ON numeric expression GOTO statement label list[ ELSE statement | 
ON numeric expression GO TO statement label list[ ELSE statement | 


ON numeric expression GOSUB statement label list [ELSE statement Way 


CALL subroutine name [(parameter list)] 
alphabetic[up to 14 alphanumerics | 


subroutine names are formed the same as numeric variable names 


expression [,... ] 
SUB subroutine name[ (argument list) ] 


variable [,... ] 


FUN function name(argument list) 
alphabetic[up to 14 alphanumeries ][$] 


funetion names are formed the same as variable names 
(and must match the data type they return) 


EXIT (in SUB subroutines) 
EXIT expression (in FUN subroutines) 


CALL CHAIN(filename[,disk unit number]) 
CALL CHAIN(string expression[,numeric expression }) 


APPENDIX A STAR BASIC Syntax 
STAR BASIC Syntax: Error Handling Statements, 
Internal I/O Statements 


Item Syntax 


Error handling statements 


ON ERROR ON ERROR executable statement 

executable statement (any statement except COMMON, DIM, DATA, IOLIST, LIST, REM, 
TITLE, SUB, FUN, END, IF-THEN-ELSE-ENDIF, FOR, NEXT) 

ERROR ERROR numeric expression 

RESET ERROR RESET ERROR 

Internal I/O 

READ READ variable list 

RESTORE RESTORE [statement label ] 


Keyboard, video, printer I/O 


INPUT INPUT [ (input control list)] variable list 
input control list [ERL=statement label ][, PROMPT=string expression ] 
«[{,CARR=numerie expression ] 
PRINT PRINT [(print control list) ] expression list 
print control list [ERL=statement label ][,CARR=numeric expression ] 
WRITE | WRITE (write control list) [expression list ] 
write control list LFN=numerie expression [,ERL=statement label | 


\[,FORMAT= string expression ][,CARR=numeric expression ] 


\[, IOLIST=statement label 


File I/O 

ALLOCATE ALLOCATE (allocate control list) 

allocate control list FILE=string expression,NREC=numerie expression, 
‘RECLEN=numerie expression |,LFN=numerie ex ression | 
4[,RECFMT=string expression |[,ORG=string expression ] 
A[,KEYLEN=numerie expression ][,ERL=statement label] 
4[,UNIT=numerie expression || ,JUNIT=numeric expression | 


OPEN OPEN (open control list) 


a open control list LFN=numerie expression ,FILE=string expression 
e ‘[,OPT=numerie expression || ,ORG=string expression | 


‘{,UNIT=numerie expression ][,IUNIT=numeric expression ] 
\[,ERL=statement label | 
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STAR BASIC Syntax 


APPENDIX A 


Item 


CLOSE 


close control list 


RENAME 


DATE 
File record I/O 
READ 


read control list 


WRITE 


write control list 


DELETE 
UNLOCK 


REWIND 
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STAR BASIC Syntax: I/O Statements 


Syntax 


CLOSE (close control list) 


LFN=numerie expression[,OPT=numeric expression ] 
‘[,ERL=statement label ] 


RENAME (LFN=numeric expression,FILE=string expression 
‘[,ERL=statement label r 


DATE (LFN=numeric expression [,ERL=statement _label]) 


READ (read control list)[ variable list ] 


[LFN=numerie expression] [IOLIST=statement label] 


‘[,EOF=statement label ][,ERL=statement label | 
‘[,KEY=string expression ][,MODE=string expression ] 
‘Puock=numare expression ][,REC=numerie expression] 
‘[,FORMATS=string expression |[,ABSOLUTE=1 


‘[,ORG=string expression | 


WRITE (write control list) [expression list] 


[LFN=numeric expression][,A BSOLUTE=1 ] 


a[,IOLIST=statement label][,ORG=string expression ] 
A[,EOF=statement label] [,ERL=statement label 


a[,KEY=string expression ][,REC=numerie expression ] 
“[,MODE=string expression ] [ »FORMAT=string expression ] 


DELETE (LFN=numeric expression[ ,ERL=statement label]) 
UNLOCK (LFN=numerie expression[,ERL=statement label ) 


REWIND (LFN=numerie expression[,ERL=statement label]) 


APPENDIX A STAR BASIC Syntax 


STAR BASIC Syntax: Sequential I/O 


Item Syntax 


ALLOCATE ALLOCATE (FILE=string expression,RECLEN=numeric expression, 


ANREC=numeric expression [,ERL=statement label ] 


A[,UNIT=numerie_ expression] ) 

OPEN OPEN (LFN=numeric expression,FILE=string expression 
A[,OPT=numerie expression ][,ORG=string expression] 
A[,UNIT=numerie expression ][,ERL=statement_label]) 


CLOSE CLOSE (LFN=numeric expression [,OPT=numeric expression ] 
A[,ERL=statement_label ]) 


READ READ (LFN=numerie expression[,MODE=string expression ] 
\[,EOF=statement label ][,ERL=statement label | 
A[,IOLIST=statement_label][,FORMAT=string expression ]) [variable list] 

WRITE WRITE (LFN=numeric expression[,FORMAT=string expression ] 


“[,MODE=string expression ] 
A[,IOLIST=statement label][ ,EOF=statement label ] 


A[,ERL=statement label] )[expression list ] 
REWIND REWIND (LFN=numerie expression[,ERL=statement_ label] ) 
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STAR BASIC Syntax: Random Access I/O Y 


Item Syntax 


ALLOCATE ALLOCATE (FILE=string expression,RECLEN=numeric expression, 


‘ NREC=numeric expression,RECFMT=string expression, 
“ ORG=string expression [,ERL=statement label ] 


‘ [,UNIT=numeric expression] ) 


OPEN OPEN (FILE=string expression,LFN=numeric expression, 


‘ OPT=numeric expression,ORG=string expression 
[,ERL=statement_ label ][,UNIT=numeric expression ]) 


CLOSE CLOSE (LFN=numeric expression [,OPT=numeric expression ] 
‘ [,ERL=statement label ]) 

READ READ (LFN=numerie expression [,REC=numeric expression | WY 
‘[,MODEs=string expression][ ,FORMAT=string expression ] 
‘ [,IOLIST=statement_label][,EOF=statement_ label ][,LOCK=numeric expression ] 


A[,ERL=statement label ])[ variable list ] 


WRITE WRITE (LFN=numerie expression[,REC=numeric expression, | 


‘[,MODEsstring expression][ ,FORMAT=string expression ] 
\[,IOLIST=statement label ][,ERL=statement label ] 


‘[,EOF=statement label] )[expression list ] 


REWIND REWIND (LFN=numeric expression[,ERL=statement_label]) 
UNLOCK UNLOCK (LFN=numerie expression [,ERL=statement label ]) 
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STAR BASIC Syntax: ISAM I/O 


Item Syntax 


ALLOCATE ALLOCATE (FILE=string expression,LF N=numeric expression, 


“ NREC=numerie expression,RECLEN=numeric expression, 
‘ RECFMT=string expression,ORG=string expression, 
“ KEY LEN=numeric expression[ ,ERL=statement label | 


“ L,UNIT=numeric expression ][,IUNIT=numerie expression]) 


OPEN OPEN (FILE=string expression,LFN=numeric expression, 
“ ORG=string expression 
* [,OPT=numerie expression][,ERL=statement label ] 


* [,UNIT=numeric expression ][,IUNIT=numeric expression] ) 


CLOSE CLOSE (LFN=numerie expression[,OPT=numeric expression ] 
‘[,ERL=statement label] ) 
READ READ (LFN=numeric expression,KEY=string expression 


“[,MODEs=string expression][ ,RORMAT=string expression ] 
‘[,EOF=statement label][,ERL=statement label | 


“ [ IOLIST=statement_ label ][,LOCK=numerie expression] ) [variable list ] 


WRITE WRITE (LFN=numeric expression[KEY=string expression ] 
*“[,MODEsstring expression ][,FORMAT=string expression] 
‘[,EOF=statement label][,ERL=statement label] 


A [ ,IOLIST=statement label ]) [expression list ] 


DELETE DELETE (LFN=numerie expression[,ERL=statement_label }) 
UNLOCK UNLOCK (LFN=numeric expression [,ERL=statement _label]) 
REWIND REWIND (LFN=numeric expression [,ERL=statement_label ]) 
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APPENDIX A 


STAR BASIC: UTILITY FUNCTION USE 


Function Name Use Type 
LEN(string expression) Takes value of the length Numeric 
of string expression 
DTE$ Takes value of the current String 


time and date in 12-digit 
ASCII string representation 


ERR Takes value of number of Numeric 
last non-{/O error code 
(See Subsection 2.3.2) 


IOERR Takes value of number of Numeric 
last [/O error ‘code (See 
Subsection 2.3.2) 


INT(numeric expression) Truncates numeric value Numeric 
aa to integer 
KEYLOCK Returns 1 if optional Numeric 


security lock is locked, 
0 if unlocked or no lock 


Pp ing expressioni, Takes value of starting Numeric 
string expression2 gesition of string expression2 
within Bring axpressioni, zero 
if not foun 
VAL(string expression) Takes numeric value of Numeric 
string expression, 
zero, if string expression 
cannot be converted to numeric 
STRS(numeric expression) Takes string value of String 
numeric expression 
EDITS(numeric_expressi: ression) 
ts numeric value String 
according to string 


(See EDITS Designators tavie) 


CHAIN(string expression (,aumeric expression) ) 
ceplaces current None 


program with program whose name 
is contained in the string expression 
from disk unit numeric expression 
(default is unit 0); 

(See Subsection, 2.7.5). 


ENVIRON(numeric variable.aumeric variable,numeric variable, 
numeric variable, aumeric variaole 
ON(n1,n2,03,n4 a3 ) None 
ceturns multi-tasking partition 
data (See Subsection C.1.3) 


WIZARD(numeric expression [,s ) 
A , sets up a duffer in 


main memory for partition data 
in multi-user’ mode. 
(See Section C.1.3.2) 


HRMP ‘Returns. 0 if orinter is not Numeric 
high resolution, a non-zero if 
orinter is hign resolution. 


MACH(string_expression (,optional ment(,s)]) 
CALL MACH 


used to ACCESS 
OSSM's in memory. Two or ‘three 
character string identifying. OSSM, 
with arguments if necessary. 


USTAT(unit) CALL USTAT returns type and 
size. information of specified disk 
unit. 

FSTAT(LIn) CALL FSTAT returns record format, 


file type and three numerics with 
file information on open file 
speeified by LFN oumber. 


Mote: Use of compiex expressions in function calls (or, for :nat matter, in keyword 


control lists or loogs, etc.) slows execution somewhat. -he amount of ime 
required for evaluating the expression being a function of the complexity of 
the expression. 


REV. E 


Uo 


APPENDIX A STAR BASIC Syntax 
STAR BASIC Syntax: Logical Operator Truth Tables 
Expression Value 
true AND true true 
true AND false false 
false AND true false 
false AND false false 
true OR true true 
true OR false true 
false OR true true 
false OR false false 
NOT true false 
NOT false true 
Precedence: 
Grouping operators first 
Mathematical operators second 
Relational operators third 
NOT fourth 
AND,OR fifth 


Where precedence is equal (AND,OR) evaluation is done left to right. 
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STAR BASIC Syntax APPENDIX A 
STAR BASIC Syntax: FORMAT Descriptors 
Type Description and Function Example 
Numeric a string of 9's with an optional decimal point: numeric 99-99 
value will be converted to digits, one digit for each 9 99999 
in descriptor; value out of range (e.g., format 99 for 9999999.9 
value 1234) is I/O error. -999999 
String a string of X's, or an X(number) where number is the *XXXX 
number of characters in the string field; one character XXXXXXXXX 
is written for each X (or, up to the number); data shorter X(20) 
than the string descriptor is blank-filled on the right; x(47) 
data longer than the descriptor is truncated; a string of X(*) 
unknown (arbitrary) length can be indicated with X(*), 
which will accept any length string presented; however, 
if X(*) is used, it must be the last descriptor in the 
FORMAT group. 
Internal* a string of I's; represents the internal numeric format 
of the D-BASIC runtime system; the first I holds the HITT 
sign of the value and its exponent; each additional I holds TH 
2 digits; descriptor must have at least 2 I's, maximum TI 
of 8 I's. ) 
Packed* a string of P's, optionally including a decimal point; PPPP 
numeric data is output as a string of Binary Coded PP.PP 
Decimal numbers, packed 2 per byte; each P holds one P.PPP 
digit (so there are 2 P's per byte); if an odd number of ‘ oe P 


* Printer use: 
does not. 


P's is specified in a descriptor, a 0 is padded on the 
right (if the same descriptor is used to read it, the 0 is 
invisible); if the value is negative, the first P in the 
descriptor holds the sign (a hexidecimal F), while if the 
value is positive, no sign is output (if required by the 
descriptor, a zero may be output, as in 3 output through 
"PP.P"; data stored would be 030); if the decimal point 
is used, it is not output, but does position the value on 
input (i.e., if 98.56 is output through descriptor PP.PP, 
9856 is output, while if P.PPP is the descriptor on input, 
the value read will be 9.856); as with numeric formats, 
if the value output cannot be read into the descriptor 
supplied for input (if PP had been given as the input 
descriptor in the example above), then an I/O error 
results; if the data has not been written in P format, 
an attempt to read it through a P descriptor results in 
an I/O error. 


will result. 
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file I/O allows use of Internal or Packed descriptors, but printer I/O 
Printer FORMAT descriptors must be Numeric or String or an I/O error 


Cy 


APPENDIX A STAR BASIC Syntax 


Character 


XX 


Other | 


STAR BASIC Syntax: EDIT$ Designators 


Significance 


Holds a place for a digit, produces a 0 if no significant digit appears in 
output value in place it holds 


Holds place for a digit, blanks if no digit present and place is to the left 
of the decimal point; acts as a 9 otherwise 


Indicates that the value is to be positioned with its decimal point at the 
V position; does not print decimal point: if one is desired, it should 
immediately follow the V (e.g., ZZZV.99 American notation, or ZZZV,99 
European notation) 


Indicates negative values with a minus - sign, positive values with no sign; 
may be used leading or trailing (or even in the middle, for special output 
coding) 


Indicates positive values with + sign, negative values with - sign; may be 
used leading or trailing (or even in the middle, if there's reason for it) 


When used in the leftmost position of the template, causes output to be 
filled with the check protect * character on the left of the first significant 
digit 

Any two identical, non-blank characters other than the ones above will 
blank any left hand, non-significant zeros, preceding the first significant 
digit with the first character of the pair 


Any other character will be blanked if it is to the left of the first 
significant digit, will be inserted literally if a digit is printed to its left 
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Syntax 


CF$(number) 
EL$ 
ES$ 


FS$[(number) ] 


PF $(page,spaces) 


CP$(X,Y) 


TAB$(number) 


BS$ [(number) | 
CR$[(number) ] 
LF$[(number) |] 


FF$[{(number) ] 


CS$[(number) ] 


APPENDIX A 


STAR BASIC Syntax: I/O Control Functions 


Operation 


Video Exclusive Functions 


Coded feature: change feature code to number (see Table 
2-7, Video Display Feature (CF$) Codes) 


Erase line: erase video from cursor positon to end of line; 
cursor does not move 


Erase screen: erase video from cursor positon to end of 
screen; cursor does not move 


Forward space: move cursor forward number of spaces; 
default is 1 space 


Printer Exclusive Function 


Printer form: set page length to page (number of lines); set 

line spacing to spaces/48 inch for 0<spaces<=127; set line 

peep. to -(spaces-128)/48 inch for 128<=spaces<=239; 240< 
aces<=255 prohibited 


Non-Exclusive Functions (Both Video and Printer) 


"Cursor" position: absolute horizontal and vertical tab to 
column X line Y 


Tab: absolute horizontal tab to column number 


Back space: move left on line number of spaces; default is 
1 space 


Carriage return: produces one or more carriage returns (no 
linefeed); default is 1 carriage return 


Line feed: advances number of lines down page (screen); 
default is 1 line feed; (no carriage return) 


Form feed: advance to top of next page (clear screen, home 
cursor to top left corner); number is number of pages 
advanced; default is 1 formfeed 


Character size: clear screen (move to top of next page); 
optional number (default is 0) changes font size: 0= no change 
(clear screen; formfeed on printer) 1= large font (clear screen; 
no formfeed on printer) 2= small font (clear screen; no 
formfeed on printer) 


X, Y, number, lines and spaces in all cases above can be replaced with a numeric 


expression with a value in the proper range, which will be truncated to integer if 


necessary. 
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STAR BASIC Syntax: Video Display Feature (CF$) Codes 


Code Features Code Features 
0 normal 8 underline 
i + highlight 9 underline,highlight 
2 blink 10 underline,blink 
3 + blink,highlight 11 underline,blink, highlight 
4 reverse 12 *underline,reverse 
5 + reverse,highlight 13 *underline,reverse,highlight 
6 reverse,blink 14 *underline,reverse,blink 
7 + reverse,blink,highlight 15 + *underline,reverse,blink,highlight 


*underline, reverse codes are equivalent to the corresponding reverse codes (i.e., reverse 
masks underline) 


+ highlight is half intensity on ADDS, double intensity on F-85. 


The CF$ function outputs a special control character to the video display. The screen 
is considered to be a single line from 1,1 to 64,16 (or 80,24), with the beginning of 
each line to the left of the end of the line above. When a control code is output, 
it appears as a blank on the screen and is effective to its right until another control 


Cy code appears. 


When the screen is cleared, it is filled with CF$(0) control characters to limit feature 
code effects. Likewise, when new lines are scrolled onto the screen, they are initially 
filled with CF$(0) characters. While this limits the effects of other feature code 
characters, good programming practice requires a CF$(0) call to terminate the output 
string. In addition, the ADDS terminal requires a CF$(0) code to terminate each 
feature if video display on the terminal is to match the console display, since clearing 
the ADDS Regent 40 screen does not fill it with CF$(0) characters. Likewise, if 
cursor control or tab functions are used within the output string, the separate parts 
of the string should be treated independently as far as feature control is concerned. 


Examples: 


PRINT (CARR=0) CS$(1),CP$(10,5),CF$(6),Message$,CF$(0) 

PRINT (CARR=0) CP$(10,7),CF$(2),"Call key operator",CF$(0) 

Header$=CS$(1)& CP$(20,1)& CF $(1)& Customer.Name$&CF$(0)&CP$(1,3)& 
CF$(1)&"Monthly Activity For "&Month$&CF$(0) 

Print (CARR=0) Header$ 
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STAR BASIC Syntax: ASCII Code (Decimal) 


1 Se 
| O | NUL|SOH/| STX |ETX| EOT| ENQLACK |BEL | BS _| HT | 
THe ve Dre TCR T So+ Sl DLE Der Dea[DCy 
| 2 [| DC4|NAK | SYN [ETB | CAN] EM|SUB/ESC|FS | GS _| 
| 3} RS{US | sSP{! | » {| #]/ $ 1% 1 & J | 


The left column gives the most signifi- 
eant digit(s), the top row the least sig- 
nificant digit. (Thus, @ is 64, DEL is 
127, ETX is 3.) 


Abbreviations: 
0 NUL Null 17 DC1 Direct control 1 
I SOH Start of heading 18 DC2 Direct control 2 
2 STX Start Text 19 DC3 Direct control 3 
3 ETX End text 20 DC4 Direct control 4 
4 EOT End of transmission 21 NAK Negative acknowledge 
b) ENQ Enquiry 22 SYN Synchronous idle 
6 ACK Acknowledge 23 ETB End transmission block 
¢ BEL Bell 24 CAN Cancel 
8 BS Backspace 25 EM End of medium 
9 HT Horizontal tab 26 SUB Substitute 
10 LF Linefeed 27 ESC Escape 
11 VT Vertical tab 28 FS Form separator 
12 FF Formfeed 29 GS Group separator 
13 CR Carriage return 30 RS Record separator 
14 so Shift out 31 US Unit separator 
15 SI Shift in 32 SP Space 
16 DLE Data link escape 127 DEL Delete 


The ASCII code set can be sent to the video display or printer by using the CHR$ 
function in a PRINT or WRITE statement with the decimal ASCII code number as the 
function's argument: CHR$(code). The CHR$ function is modulo 256, so the possible 
range is 0 to 255, with the higher numbers repeating the 0 to 255 codes. Additional 
uses of the CHR$ function are found in the two tables which follow. 
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“A 
Normal 
128 
129 
130 
131 
132 


133 


134 


135 


136 


137 


138 


Codes 139 to 143 and 155 to 159 are illegal and should not be used. 
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STAR BASIC Syntax: Video Graphic Character (CHR$) Codes 


Blink 


144 


145 


146 


147 


148 


149 


150 


151 


152 


153 


154 


Name 


Top Left Corner 


Top Right Corner 


Bottom Left Corner ' 


Bottom Right Corner 


Top Intersection 


Right Intersection 


Left Intersection 


Bottom Intersection 


Horizontal Line 


Vertical Line 


Crossed Lines 


Character 


+/—} | JE JT} i} LIT |} 


The F-85's video graphic character set can be generated by using the CHR$ function 


in PRINT statements with the code set at the desired graphic character. 


These codes 


are above (and in addition to) the ASCII character set described in Table 2-8. 
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Key 


Normal 


STAR BASIC Syntax: Keyboard Codes 7) 


Shift 


F-85 Standard Keyboard 


ONKMS<CHUWOVOZESrRU-moOMmVAUD 


— 
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32 
27 


9 
127 
24 
13 


Code 


Error 105 


Printer resume 


Top of form 
on printer 


APPENDIX A 


Remarks 


Code ESC is an automatic error 
105. 


Use Normal value for all keypad 
keys 


APPENDIX A STAR BASIC Syntax 


©) STAR BASIC Syntax: Keyboard Codes (cont'd.) 
Key Normal Shift Code Remarks 
2. 50 64 Set top of form 
on printer if STOP 
is down 

3 51 35 Print screen 
4 52 36 _ 
5 53 37 _ 
6 54 94 —_ 
7 55 38 _ 
8 56 42 — 
9 57 40 = 
= 45 95 31 45 only on keypad 
= 61 43 - 

91 93 27 

92 124 28 
; 59 58 29 

39 34 30 
; 44 60 — 44 only on keypad 
: 46 62 _ 46 only on keypad 
/ 47 63 _ 


©) apps Regent 40 


Like the F-85, alphanumeric and numeric keys generate the normal ASCII code for 
their character(s). Keys which generate special codes are listed below. 


BREAK _ _ _ Generates a 500-millisecond spac- 
ing condition on the output line. 


CONTROL — = —. When used with any alphanumeric 
key, sets the seventh bit of that 
key's ASCII code to zero (subtract 
64 from the decimal ASCII code). 


DEL 95 127 oo 
ENTER 13 13 — 
NEW LINE 13 13 as 
ERASE -_ _ - ERASE alone erases to the end of 


line; CONTROL SHIFT ERASE 
erases to end of page (end of 
sereen)} CONTROL ERASE clears 


sereen. 
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STAR BASIC Syntax: Keyboard Codes (cont'd.) 


Key Normal _ Shift Code Remarks 

ESCAPE 27 QT — 

LINE FEED 10 10 — 

LOCAL _ _ _ Enters or leaves LOCAL mode 


(data link maintained but all trans- 
fer stopped). 


SHIFT - —_ —_ Toggles the sixth bit of the ASCII 
code when used with an alpha- 
numeric key (adds or subtracts 32). 
SHIFT-ESCAPE causes an alpha- 
shift lock. 


HOME 1 1 — 

Arrows: 

Up 26 26 ae 

Down 10 10 = 

Right 6 6 = 

Left 21 21 _ 

AUX a = = Enables or disables auxiliary port 


(if enabled, auxiliary port receives 
all data from the keyboard and 
the F-85, for logging or hard-copy 
echo, for instance). 


Special Function Keys: 


Fl 2 49 2 33 me The special function keys all gen- 
F2 2 50 2 34 _ erate two bytes, a STX followed 
F3 2 51 2 35 = by another character. 

F4 2 52 2 36 = 

F5 2 53 2 37 _ 

F6 2 54 2 38 

FT 2 55 2 39 = 

F8 2 56 2 40 = 
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STAR BASIC Syntax: Video, Printer Font Characteristics 


Printer Video 
Large CS$(1),PF$(66,8) CS$(1) 
Font: 10 characters/inch 7 x 9 dot matrix 
Line length: 132 characters/line 64 characters/line 
Line spacing: 6 lines/inch 4 lines/inch 
Page size: 66 lines/page 16 lines/screen 
Small CS$(2),PF$(66,8) CS$(2) 
Font: 16.5 characters/inch 5 x 7 dot matrix 
Line length: 217 characters/line 80 characters/line 
Line spacing: 6 lines/inch 5 lines/inch 
Page size: 66 lines/page 24 lines/screen 
Default: Large Large 


Note: All printer characters are 9 x 9 matrix, with the horizontal pitch compressed 
to create the small font characters. Video characters, on the other hand, change 


a matrix size. 


To set font and form: 


Printer: WRITE (LFN=0 [,ERL=statement label]) CS$(number),PF$(page,spaces) 
Video: © PRINT CS$(number),CF$(number) 


where CS$ sets font, line length (and page size on video), PF$ sets page size 
and line spacing on printer, CF$ sets video display format. 


Printer: WRITE (LFN=0,CARR=0[,ERL=statement label]) CHR$(27),CHR$(12),CHR$(0) 


sets top of form at current paper position. 
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STAR BASIC Syntax: Printer Boldface (Overstrike) Procedure UO 
WRITE (LFN=0,CARR=0) expression,BS$(LEN(expression)),expression 
or 


WRITE (LFN=0,CARR=0) TAB$(Number),expression, TAB$(Number),expression 


The second alternative has the advantage that if more overstrikes are desired for an 
even darker boldface, addition of a statement label and a transfer statement allows 
as many iterations as desired. The first alternative has the advantage that knowledge 
of the print position is unnecessary: the line will produce a boldface expression wherever 
used. (Note: if the LEN function is used, the expression must be string in type, or 
converted to string.) 
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STAR BASIC Syntax: ALLOCATE Controls 


Control group 
Name and Use 


FILE=string expression 


file name 


NREC=numerie expression 


number of records 


RECLEN=numerie expression 


record length 


LFN=numerie expression 
logical file number 


RECFMT=string expression 


record format 


ORG=string expression 
file organization (type) 


KEYLEN=numeric expression 


key length 


ERL=statement label 
error line 


UNIT=numerie expression 


disk unit 


IUNIT=numerie expression 


ISAM index disk unit 


Range 


up to 10 characters, 
first one alphabetic 


0-65535 bytes (sequential) 
1-65535 records (random, ISAM) 


0-255 bytes (sequential) 
1-512 bytes (random) 
2-512 bytes (ISAM) 


1-specified maximum 
(see Subsection 1.1) 


"E"=fixed 
"V"=variable 


"S"=sequential 
"R"=random access 
"I"=ISAM 

2-24 bytes (characters) 


valid statement label 
(up to 32 characters) 


0 to 7 


0 to 7 


Default value 


no default value 


no default value 


no default value 


no file number specified 


ny" 


tgtt 


no length specified 


no error trap set 


unit 0 


unit 0 


ALLOCATE statements are used to create disk data files. 


The ALLOCATE statement 


reserves space on the diskette, adding the filename to the disk directory. However, 
no actual data are written to the disk until it is opened and written. Since data files 
are of three types, sequential, random access and Indexed Sequential Access Method 
(ISAM), ALLOCATE statements come in three forms. 
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STAR BASIC Syntax: ALLOCATE Record Sizing 


Field 
Type 


string constant 


string variable 


string array 


numeric value 


Record 
Type 


Sequential record 
(variable length) 


Random access record 
(fixed length) 


ISAM data files 
(fixed length) 
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Format 


default 


X format 
(String) 


default 


X format 
(String) 


default 


X format 


(String) 
default 


9 format 
(Numeric) 


I format 
(Internal) 


P format 
(Packed) 


Length 


field length 


field length 


field length 


Size 


1 byte/character 


length of format descriptor 
(1 byte/X) 


1 byte 


length of descriptor 
(1 byte/X) 


DIM length 


length of descriptor 

(1 byte/X) 

variable: up to 21 bytes (output as 
ASCII string as in PRINT statement: 
1 byte/character up to 21; includes 
leading blank, sign, exponent and so 
on) 


1 byte/9 or . 
(each 9 holds 1 digit) 


1 byte/I; minimum 2, maximum 8 
8 (1 I holds exponent and sign; each 
additional I holds 2 digits 


1/2 byte/P (. not output) 
(each P holds 1 digit) 


Maximum length 


255 bytes 


512 bytes 


912 bytes 
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STAR BASIC Syntax: Video/Printer Control Function Sizing 


Name 


feature code 


erase line 
erase screen 
forward space 


printer form 


position 
tab 

-) backspace 
return 
linefeed 
formfeed 


clear screen 


Control 
Code 


CF$(n) 


EL$ 

ES$ 

FS$ (n) 
PF $(x,y) 


CP$(x,y) 
TAB$(n) 
BS$ (n) 
CR$ 

LF$ (n) 
FF$ (n) 
CS$ (n) 


ASCII 
Sequence 


single byte 
special code 
ESC RS 
ESC GS 
ESC SP n times 
if y NE 0 

ESC LF y 
if x NE 0 

ESC SOH x 
ESC HT x ESC VT y 
ESC HT n 
BS n times 
CR 
LF n times 
FF n times 
FF (when n=0) 


ESC ETX (n=1) 
ESC EOT (n=2) 


Size 
In Bytes 


2 
2 


2*n (default is 2 bytes) 


3 

3 (total: 6 bytes if both) 
) 

3 

n (default is 1) 

1 

n (default is 1) 

n (default is 1) 

1 (default is 1) 


2 
2 


If video/printer control functions are sent to disk files instead of to the printer or 
video display (as, when a print file is "spooled" in multi-user applications, waiting for 
the printer to be free for output) the control functions are stored as strings of ASCII 


code as shown above. 


Thus, the EL$ function takes two bytes (for ESC and RS). 
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Control Group 
Name and Use 


FILE=string expression 


file name 
LFN=numeriec expression 
logical file number 


ORG=string expression 


organization 


OPT=numeric expression 


file access option 
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STAR BASIC Syntax: OPEN Controls 


Range 


alphabet character followed by 


Default Value 


no default value 


up to 9 printable characters 


0-specified maximum (0=printer) 


no default value 


(see Subsection 1.1) 


"S" = sequential i 
"R" = random 
"" = ISAM 
Sequential 
0 = read only 0 
1 = write or rewrite only 
(from beginning of file) 
2 = write extend (from end of file) 
7 = read only exclusive access 
Random 
3 = update (read or write) default is 0, 
(only legal option) whieh is illegal 
4 = read only access for opened 
files that are single-writer/ 
multi-reader. 
5 =  single-writer/multi-reader access; 
allows read only access by other 
user who must open the file 
OPT=0 or 4 
6 = update (read or write) 


exclusive access 


REV. E 


UO 
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STAR BASIC Syntax: OPEN Controls 


Control Group 
Name and Use Range Default Value 


The following chart lists the allowed (OK) and disallowed (ERR) OPEN options for 
non-ISAM files. File access mode conflicts are reported as an error 12. 


{st User File OPEN’d with OPT= 
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Control Group 
Name and Use 


STAR BASIC Syntax: OPEN Controls (cont'd) 


Default Value 


Range 

ISAM 

0 =~ read or write, multi-access 0 

1 =~ read only, multi-access 

2 =~ read or write, exclusive 
access 

3 = read only, exclusive access 

6 =~ fast sort, read or write, 
exclusive access 

7 = same as option 3 

10 = _ file cleared, read or write, 
exclusive access 

14 = file cleared, fast sort, read 
or write, exclusive access 

18 = __ single-writer/multi-reader 
other users must open 
file OPT=1 


all other numbers are illegal entries 


NOTE: READ ONLY means, writes to the file are not allowed. EXCLUSIVE ACCESS 
means, only one user may access the file. Exclusive use is required for CLOSE (delete), 


DATE and RENAME statements. 


FAST SORT means, delayed write buffering reduces 


the number of disk accesses; speeding sorts and other data manipulations. CLEAR 
FILE means, clear the contents of the file (for scratch file use primarily). This deletes 
all records but does not require that the file be reallocated. 


UNIT= numeric expression 0-7 


disk unit 


(data file unit for ISAM) 


IUNIT=numerie expression 0-7 
ISAM index file disk unit 


ERL=statement label 1-32 alphnumerics, the first 


error trap line 


A-39-0 


alphabetic, or a numeric string 


no default 
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STAR BASIC Syntax: CLOSE Controls 


season aha Range Default value 
Name and use 

LFN=numeric expression 0-specified maximum (0=printer) no default value 
logical file number (see Subsection 1.1) 

OPT=numeric expression 0 = normal close 0 
close option 1 = deletion close (file killed)* 


truneation close (unused 
space at the end of a 
sequential file eliminated; 
eannot be used with random 
or ISAM files) 


2 


ERL=statement label valid statement label no default value 
error trap target line (alphabetic followed by up 
to 31 alphanumerics, or 
string or numerics) 


*ISAM files must be open for exclusive access (OPT=2, 3, 6, 7, 

10, or 14) to be deletion closed. An attempt to close delete an 
ISAM file which is not open exclusive access results in an I/O 
error. 
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STAR BASIC Syntax: READ Controls 


Control group 
Name and use 


LFN=numerie expression 


logical file number 
MODEsstring expression 


access mode 
(see Mode Table 


FORMAT=string expression 
input data format 


EOF=statement label 
end-of-file trap 


ERL=statement label 
general 1/0 error trap 


ae Se et 
key to ile 
REC=numerie expression 


random file record number 


LOCK=numerie expression 


ISAM record lock 


IOLIST=statement label 
supplies variable list 


ABSOLUTE=1 
disk sector read 


UNIT=numerie expression 


disk unit 
(data file unit for ISAM) 


IUNIT=numeriec expression 


ISAM index file disk unit 


Range 


1-specified maximum 
(see Subsection 1.1) 


"S" = sequential 
"R" = random 
special characters 


(see FORMAT Table) 


valid statement label 
valid statement label 


2-24 characters in length 
(if MODE="S", key must 
be a string array name) 


1-65535 


0 
1 


unlocked 
locked 


label of an IOLIST 
statement 


1 


0-7 


Default value 


no default value 


ng 


same as PRINT 
statement 


automatic error handling 


automatic error handing 


no default value 


no default value 


defaults to variable 
list required 


defaults to normal 
file read 


0 


Note: When the ABSOLUTE parameter is used, REC must be used to specify 
the sector to be read; REC range then becomes 0 to disk size. 
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File is: 
Random 
Random 


ISAM 
ISAM 


Sequential 
Sequential 
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STAR BASIC Syntax: READ Modes 


Mode is: 
"Rt" 
"gir 


Rit 
ng 


Rit 
ngit 


Operation is: 
read by record number 
read sequentially by record number 


read by key value 
read next record (by key order) 


illegal 
read next record 


Nee enn ne een eee 
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STAR BASIC Syntax: WRITE Controls 


Control Group 


Name and Use Range Default Value 


LFN=numerie expression 1-specified maximum (0=printer) no default value 


logical file number (see Subsection 1.1) 
MODE=string expression "S" = sequential "st 
access mode "R" = random 
(see Mode Table) 
FORMAT=string expression special characters same as PRINT 
output data eee (see FORMAT table) statement 
EOF=statement label valid statement lable no default value 
end-of-file error trap 
KEY=string expression 2-24 characters in length no default value 
key to ISAM file 
REC=numerie expression 1-65535 no default value 
random file record number 
IOLIST=statement label label of an IOLIST statement defaults to expression 
supplies expression list list required 
ABSOLUTE=1 1 defaults to normal 
disk sector read file write 
UNIT=numerie expression 0-7 0 
disk unit 
(data file unit for ISAM) 
IUNIT=numeric expression 0-7 0 


ISAM index file disk unit 


Note: When the ABSOLUTE parameter is used, REC specifies which sector is to be 
written. REC range then become 0 to disk size. 
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STAR BASIC Syntax: WRITE Modes 


File Type Mode Designation Operation 
Random access MRM write by REC record number 
“ write next record (by record number sequence) 
Sequential ae illegal 
nS" write next record 
ISAM "R" rewrite current record (last record read) 
ng write-add by KEY value 
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A.2 Sample Programs 


Three sample programs follow. The first, TACK, is an implementation of a familiar 
game. It illustrates STAR BASIC programming techniques and use of the video displav. 


The second program, COFFEE, is a file maintenance program. It illustrates basic file 
usage and is an example of a small menu-driven program. 


The third sample program, REFERENCE, gives a cross-reference listing of the instances 
of a sought string within a text file. REFERENCE illustrates basic I/O techniques as 
well as hardcopy output. 


None of these programs is a finished application. They are not intended as illustrations 
of the only way to program in STAR BASIC but rather are illustrations of a few of 
the techniques used in writing clear, maintainable, well-structured STAR BASIC pro- 
grams. There are many good and useful programming techniques not shown here; these 
are given as samples useful in learning the language. 


Sample Program, TACK APPENDIX A 


TIC TAC TOE Program 


TITLE "TACK -- MAIN LOGIC” 


GOSUB INITIALIZE ialso contains reinit routine 
GOSUB DISPLAY hintroduction only 
GOSUE PLAY icontains replay/end routines 


TITLE "TACK --~- INITIALIZATION ROUTINE" 
H initialize variables 
INITIALIZE: 


DIM EX$(51,-9) iX reversed, in the 9 # fields 
DIM OH# (45-9) 'O reversed, in the 9 # fields 
DIM X1#(4) ipart of top, bottom of X 
DIM X2%(5) ipart of middle of X 
DIM 01%(9) itop rbottom of O 
DIM 02% (9) imiddle of O 
DIM CrossHatch#$(500) i#, with cue numbers in each field 
DIM SCREENS (1024) iscreenful of message 
DIM LINES (100) tl line of screenful 
DIM PROMPTS (80) iprompt line for play 
DIM IN$(10) tholds all input 
H BLANKS =" oN 
H BELLS rings bell 
H COUNT counter 
H X, Yr, I loop index variables 
' Pp parameter, passes value of INS 
H Pi holder for P value after pass 
, R$ reverse video 
' BS blinking video 
H NS normal video 
REINIT: talso to reinitialize for replays 
CALL UPDATE (19) iset common to @ 
R$=CFS (4) ireverse video 
BS=CFS (2) iblinking video 
NS=CFS (0) inormal video 
X1S2RSE" XX" ENG ipiece of top, bottom of X 
X2$2=RBR" XXX" RNG imiddle of x 


OLS=RSF&"OOOOOOO" ENS top, bottom of O 
OZS=RS&"OO"BNSE" "BREK"OO"BNGS imiddle of O 


BLANK$=""_" ia blank space 

BELLS=CHRS (7) Irings bell 

COUNT=0 tcounter 

X=@ 'index variable 

Y=@ tindex variable 

T=@ 1index variable 
SCREENS=BLANKS iscreen messages 
LINES=BLANKS iSingle lines of messages 
INS=BLANKS tall input 
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) IF PROMPT#<>"" THEN RETURN ishorten reinitializations 


PROMPT % 
holds play command prompt 


PROMPT#=CP#(1,16)8EL$&"What is your move? " 


EX and OHt 
loop sets reverse X and O in EX# and OHS 


with cursor positioning for # fields 1 to 9 


COUNT=0 
FOR Y=12 TO 2 STEP -5 
FOR X=11 TO 53 STEP 21 
COUNT=COUNT+1 


EX#(1,COUNT) =CP#(X-3,Y-1) & X1$ & 
. CPE(X+2,Y-1) & X1$ & 
a CPS(X-1,Y) & XZS & 
s CPS(X-3;,Y+1) & X1% & 
m CPS(X+2,Y+1) & X1% 
OH$ (1 ,-COUNT) =CP#(X-3,Y-1) & 01% & 
s CPS (X-3,Y) & O2S & 
bi CPS(X-3,Y+1) & O1% 
NEXT X 
an NEXT Y 
H CrossHatch$ 
} next, build the # in reverse blanks 
CrossHatch#="" istart at null 
FOR Y=1 TO 15 115 screen lines 
IF Y=5 OR Y=10 THEN GOTO Ears ihorizontal bars 
FOR X=21 TO 42 STEP 21 ivertical bars 
CrossHatch#=CrossHatch$&CPs (X,Y) &RESBLANKSENS 
NEXT X 


EHatch: NEXT Y 
' now put blinking ID numbers in center of each # Field 


COUNT=@ iset counter 
FOR Y=12 TO 2 STEP -5 'Y=2, 7 or 12 
FOR X=10 TO 52 STEP 21 iX=19, 31 or 52 
COUNT=COUNT+1 icount 1 to 9 
CrossHatch$=CrossHatch#&CPs$ (X,Y) SES COUNTENS 
NEXT X 
NEXT Y 
RETURN ite main logic 
Bars: X=1 ihorizontals 
CrossHatch$=CrossHatchs&CP$(X,Y)&2R$ i begin line 
FOR I=1 TO 62 | add 62 
CrossHatch$=CrossHatch$&BlaNnks i Teversed 
i blanks 


NEXT I 
( ) CrossHatch$=Cr ossHatch$&Ns 
GOTO EHatch 


normal video 
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APPENDIX A 


TITLE 


"TACK -- FIRST DISPLAY ROUTINE” 


this starts the game 


DISPLAY:PRINT BELLS 


DLoop: 


Hold1: 


Display2: 


FOR J=1 TO 3 
PRINT CS#(1) 


PRINT (CARR=®) CrossHatchs 


FOR I=1 TO 9 
PRINT 
NEXT I 
FOR I=1 TO 9 
PRINT (CARR=0) 
NEXT I 
NEXT J 


(CARR=0) EX$(1,1) 


OH# (1,1) 


IF KEYIN@=""" THEN GOTO DLoop 


title is next 


PRINT CS#(1) 

RESTORE Screentl 

GOSUB ScreenSet 

PRINT (CARR=0) SCREENS 
IF KEYIN#=""" THEN GOTO 


PRINT CS#(1) 

RESTORE Screen2 

GOSUB ScreenSet 

PRINT (CARR=0) SCREENS 
INPUT (CARR=®) INS 

IF INS="N" OR IN#S="NO" 
IF IN#="n" OR INH="NO” 


Instructions: 


Hold2s 


PRINT CS$(1) 

RESTORE Screen3 

GOSUE ScreenSet 

PRINT (CARR=0) SCREENS 
IF KEYINS="" THEN GOTO 
RETURN 


ScreenSet: 
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SCREEN$="" 

READ COUNT 

FOR I=1 TO COUNT 
READ LINES 
IF I=1 THEN 


Holdi 


ido they want instructions? 


THEN RETURN 
OR IN$="No" 


Hold2 


THEN 


ining bell 
iflash 3 times 
iClear screen 
iprint # 


iprint all X’s 


iprint all 0O’s 


iloop until "go" 


iclear screen 


iset data 
iprint it 
ireading wait 


‘clear screen 


iget data 
iprint it 
tinstructions? 
ino = return 
RETURN 
tinstruct ‘em 
‘clear screen 


iget data 
iprint it 
iread wait 

ito main logic 


iset SCREENS 
‘initialize 
inumber of lines 


‘get line 
1add formatters 


SCREENS=LF$ (5) &BELLS& CENTERS (LINES) & 
CFS (1) &LINESENSELF S$ (2) 


ELSE 


SCREENS=SCREENS&LF S& CENTERS (LINES) &LINES 


ENDIF 
NEXT I 
FETURN 
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Sample Program, TACK 


TITLE “TACK -- DISPLAY DATA SECTION" 
Screenl:DATA 4 inumber of lines 
DATA "TIC TAK TOE” idisplay lines 
DATA "This is a tic tak toe game." 
DATA "I hope you are a good player.” 
DATA "(Type any key to go on.)" 
ScreenztDATA 2 
DATA "TIC TAK TOE” | 
DATA "Do you wish instructions?" 
Screens:DATA 6 
DATA "TIC TAK TOE" 
DATA "The nine empty squares of the TIC TAK TOE board" 
DATA "are numbered from 1 to 9. To play," 
DATA "simply input your choice after the prompt." 
DATA "You get the first move and the X, I’11 take” 
DATA "the O’s. Good luck! (Type any key to start play.)" 
TITLE "TACK -~- PLAY ROUTINE" 
PILLAY: PRINT (CARR=0) CS$(1) -CrossHatchs iset up screen 
PLoop! INPUT (CARR=@,PROMPT=PROMPT$) IN& iget move 
P=VAL (INS) ‘set holder 
IF P<1 OR P>9 THEN itest input 
PRINT (CARR=@) BELLS i not 1 to 9: 
GOTO PLoop | ding and back 
ELSE i is 1 to 9: 
Pi=p rpreserve value 
CALL UPDATE (P) i choose O move 
IF P<1 THEN GOTO PLoop ‘duplicate move 
PRINT (CARR=@) EX$(1,P1) iprint X move 
IF P=9 THEN GOTO EPLoop rend of game 
PRINT (CARR=®) OH$(1,P) i print 0 
ENDIF 
GOTO PLoop iget next move 
EPLoop: PRINT (CARR=@) BELLS igame ends, ding 
IF P=10@ THEN '19@ is a tie 
CALL TIE (CrossHatch#?) 
GOTO PWait 
ENDIF 
IF P>10@ THEN 1>10@ calls tie 
PRINT (CARR=®) OHS(1,-P-100) print my move 


CALL TIE (CrossHatch#) 
GOTO PWait 
ENDIF 


TF P=19 THEN 
PRINT (CARR=@) CP#(1,16) -EL- 
‘ "CONGRATULATIONS -- YOU WINE" 


‘and it’s a tie 


:they win 


'Give congrats 
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PWait: 


TLILe 


ELSE ithey lose 
P1=P\1#1@ icrossline code 
P=P-P\1 
PRINT (CARR=@) OH#(1,P-10) 

CALL CrossLine(P1) 
PRINT (CARR=90) CP#(1,16) -EL$, 


"I win -- good game” iso sorry 
ENDIF 
FOR I=1 TO 590@ 'wait a second 
NEXT I iwhile they read 
PRINT (CARR=@) CP#(1,16) -EL® iplay another? 


PRINT (CARR=O) "Do you want to play another? " 
INPUT (CARR=@) INS 

IF INS="N" OR INS$="NO" 

OR INS="n" OR INS="no" OR INS="No" THEN tend it 


PRINT CS#(1) iclear screen 
ELSE 
PRINT CS#(1) 1yes or nonsense 
GOSUB REINIT iinitialize and 
GOTO PLAY iplay again 
ENDIF 
END 


"TACK -- UPDATE SUBROUTINE" 
SUB UPDATE (P) 


| HHH HHEH INITIALIZATION SECTION 


DIM A(1®) ‘holds current status code 
1A(1@) holds move counter 


opponent’s square (X here) 
nothing here (blank) 
my square (0 here) 


Ss 
iow on 


eee 


+ 
Ww 
ce 
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Ss 


oo <= we oe 


ew oe ow oo 


DIM T(8) ‘holds line values 
Td) T(2) T(3) 
xtot Ha } 3X 
Nit 1x} i 3X 
xiot 1x! ee 4 
T(4) T(5) T(6) 
it 1 ot MUXIX 
; 4 NIXNIN 1 4 
xixtx 4 | 
T(7) T(8) 
ee 4 xi of 
txt ix? 
xi | is 
DIM T#$(3,8) 


TS holds the A() codes corresponding to a T() line; 
where T(4) = A(1)+A(2)+A(3) » 
TS(1,4) = "123", For instance 


COMMON A iin the common so values remain 


| HHHHHEHHACTION SECTION 


IF P>9 THEN tif P>9 then initialize common 
FOR I=1 TO 10 
A(1) = 
NEXT I 
EXIT 
ENDIF 


IF A(P)<>®@ THEN iduplicate move, bounce it 
PRINT (CARR=@) CP#(1,16) ,-EL$,CHRS(7) » 
"Sorry, duplicate move.” 


P= '@ = back to input loop 
FOR I=1 TO 500 iwait while they read it 
NEXT I 
EXIT 
ENDIF 
A(19) =A(1@) +2 tincrement move counter 
A(P)=-1 imark passed-in move 
GOSUB TSet iset T() lines 


FOR J=1 TO 3 
FOR I=1 TO 8 

ON J GOSUB TheyWinTest,IWinTest MoveTest 
NEXT I 


NEXT J 
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‘WE’VE GOT A FREE MOVES ww 


i if we can get the center, grab it 
IF A(5)=@ THEN 
A(5)=1 
=5 
GOTO XIT 
ENDIF 


H if I can threaten to win; do it 
FOR I=1 T0 8 
IF T(I)=1 THEN 
FOR J=1 TO 3 
COUNT=T$(J,131) 
IF A(COUNT)=@ THEN 
A(COUNT) =1 
P=COUNT 
GOTO XIT 
ENDIF 
NEXT J 
ENDIF 
NEXT I 


H pick @ corner and grab it 

N=7 

GOSUE ZTEST Lf 
N=1 

GOSUB ZTEST 

N=3 

GOSUB ZTEST 

N=9 

GOSUB ZTEST 


okay, take anything we can get 

N=8 

GOSUB ZTEST 

N=4 

GOSUB ZTEST 

N=2 

GOSUB ZTEST 

N=6 

GOSUB ZTEST 


H if we’re here, the game’s over and it’s a tie 


Tie: P=100 
EALT 
TSet: T(1) 3A(1) +A(4) +4(7) ivertical 1 
TS(1,1)="147" iA) codes of T(1) 
T (2) =A (2) +A(5) +A(8) ‘vertical 2 
TS(1,2)="259" 1A() codes of T(2) VW 
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T (3) =A (3) +A (6) +A (9) 
T$(1,3)="369" 

T (4) =A (1) +A (2) +A(3) 
TH (1,4) ="123" 

T(5) =A (4) +A(5) +A (6) 
T$(1,5)="456" 

T (6) =A (7) +A(8) +A(9) 
T$(1,6) ="789" 

T (7) =A(1) +A (5) +A09) 
T$(1,7) ="159" 

T (8) =A(3) +A (5) +A(7) 
T$(1,8)="357" 
RETURN 


TheyWinTest: 
IF T(I)=-3 THEN 


Sample Program, TACK 


nents 


ivertical 3 

iA() codes of T(3) 
ithorizontal 1 

'At) codes of T(4) 
thorizontal 2 

iA() codes of T(5) 
thorizontal 3 

tA) codes of T(6) 
idiagonal 1 

'A() codes of T(7) 
idiagonal 2 

tA) codes for T(8) 


CALL CrossLine(I) 


P=10 

EXIT 
ENDIF 
RETURN 


IWinTest: 
COUNT=0 
IF T(I)=2 THEN 
FOR K=1 TO 3 


COUNT=TS$ (Kr T31) 

IF A(COUNT)=@ THEN 
A(COUNT) =1 
P=COUNT+10+1/19 
EXIT 

ENDIF 

NEXT K 
ENDIF 
RETURN 


MoveTest: 
IF T(I)=-2 THEN 
FOR K=1 TO 3 
COUNT=TS#(K,131) 
IF A(COUNT)=® THEN 
A(COUNT) =1 
=COUNT 
GOTO XIT 
ENDIF 
NEXT K 
ENDIF 
RETURN 
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WinCheck&é 


ZTEST: 


XIT: 


TETLE 


TITLE 


FOR I=1 TO 8 
IF T(I)=3 THEN 
P=COUNT+1041/10 
EXIT 
ENDIF 
NEXT I 
RETURN 


IF A(N)=0 THEN 
A(N) =1 
P=N 
GOTO XIT 
ENDIF 
RETURN 


IF A(10)=8 THEN icheck for automatic ties 
IF P>9 OR P<1 THEN EXIT 
A(P) =1 
GOSUB TSet iset my move in T() lines 
FOR I=1 TO 8 
IF T(I)=-2 THEN EXIT :it’s not a tie 
NEXT I 
P=P+10@ iplay my move and declare tie 
ENDIF 
EXIT 
END 
"TACK -~ CENTERING FUNCTION SUBROUTINE" 
FUN CENTERS (A$) 


DIM A#%(1) idummy dim of argument 
=LEN (AS) ihold length of line 
EXIT TABS (32-N/2) icenter line 

END 


“TACK -- TIE SUBROUTINE" 
SUB TIE (CrossHatch$) 


DIM CrossHatch$(1) idummy dim 
DIM T#(39,9) iTIE (like X) 
COUNT=0 


FOR Y=12 TO 2 STEP -5 
FOR X=11 TO 53 STEP 21 
COUNT=COUNT+1 
TS (1 ,COUNT) =CPS (X-4,Y-1) &CFS (4) &"TIETIETIE"&CFS(Q) 
&CPS(X—-1,-Y) &CFS (4) &"TIE"&CFS (OD) 
&CPS(X—-1,Y+1) &CFS$ (4) &" TIE "SCF S(O) 
NEXT X 
NEXT Y 
PRINT (CARR=0) CS$(1) ,-CrossHatchs 
FOR I=1 TO 9 
PRINT (CARR=0) T$(1,1) 
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TITLE 


"TACK -- WINNING CROSSOUT SUBROUTINE" 
SUB CrossLine(N) 


Sinitialization 


VERT: 


DIAG: 


DIM LINES (20@) iholds output line 
DIM HOR$(462) FIXED tholds horizontal 
DIM 87%$(7) FIXED 17 blanks 

DIM BS5%(5) FIXED ‘5 blanks 
BLANK$="" "' iblank space 
B7$=BLANKS iset to blanks 
B5$=BLANK$ iset to blanks 
R$=CFS (4) ireverse video 
N#=CF S$ (@) inormal video 
LINE$="" imull it 
HORS=BLANKS ‘fill with blanks 


ON N GOSUB VERT,VERT,VERT »HORZ,HORZ»HORZ DIAG, DIAG 
PRINT LINES 
EXIT 


IF N=1 THEN X=8 

IF N=2 THEN X=29 

IF N=3 THEN X=50 

FOR Y=1 TO 15 

ON Y GOSUB VSet -VSet ,VSet,VSet,NI, 

VSet ,VSet ,VSet ,VSet,NI- 
VSet ,VSet ,-VSet ,VSet,VSet 

NEXT Y 

RETURN 


LINES=LINES&CPS (X,Y) &REEB7S 
RETURN 


IF N=4 THEN Y=12 

IF N=5 THEN Y=7 

IF N=6 THEN Y=2 
LINES=CP$ (1,Y) &RE&HORSENS 
RETURN 


IF N=7 THEN RESTORE D7 
IF N=8 THEN RESTORE D8 
FOR Y=1 TO 15 
ON Y GOSUB DG,DG,DG-DG-NY, 
DG »DG,DG -DG »NY ta 
DG,DG,DG,0G,DH 


NEXT Y 
RETURN 


Sample Program, TACK 
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DG: 


DB: 


READ X 
LINES=LINES&CP$ (X,Y) &RS&B5S$ 


RETURN 


READ X 
LINES=LINES&CPS$ (X,Y) &R$& BSS (3) 
RETURN 


DATA 59,54,49,44 
DATA 38,33,28,-23 
DATA 17,13, 9, 5, 1 


DATA 1, 6711716 
DATA 23,28,33,38 
DATA 44,48,52,56,59 


END 
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Cy 


APPENDIX A COFFEE 


NE 


TITLE 


"COFFEE -- MAIN LOGIC" 
tris does the coffee payment list by departments 


GOTO Initislize 'set up, then call MM 

GOSUE MainMenu 

ON Menu GOSUB PEngin,PAdmin »PManefact ;PMarket -AddNames » 
Of fFNames;,Initiate-,EndIt ELSE GOTO MM 

GOTO ReInit ithis sets back up and calls MM 

OUTPUT external subroutine does printing 


"COFFEE -- INITIALIZATION ROUTINE” 


Initialize: 


ReInit: 


DIM D#(5) ,Inputs(50) ,T$(1) BASED Depts (20) 
DIM Key#(15) FIXED, Name$(5@) ,InName$ (50) ,-Line#(20) 


OPEN (LFN=0) 


Dt holds dept file name 

Inputs gets input from questions 

TS ist character of Input% 

Depts holds printable dept names 

Keys holds ISAM file keys 

Namet holds ISAM file records (names) 
InNames alternate Names for delete test 
Linet holds main menu print lines 


Ds= " u 

Input$=Ds 
Dept$=Ds 

Key $=Ds 

Name$=D¢ 
InNamet=DS 
Line%=D$ 

BASE TS AT Input 
Menu=0 

GOTO MM 


"COFFEE -- DATA SECTION" 
this holds data statements 
DATA "1) Print Enginrng"”, 
"5) Add name", 
"2) Print Admin", 
"6) Delete name", 
"3) Print Manufact”, 
"7) Initialize files", 
"4) Print Marketing”, 
"8) End Program" 


"COFFEE -- MENU PRINT AND INPUT ROUTINE" 
this prints the main menu and inputs the response 


COFFEE APPENDIX A 


MAINMENU: 
PRINT CS#(1) ,-CP$(10,1)-"DURANGO SYSTEMS COFFEE LIST" 
9 &" MAIN MENU” 
RESTORE MMDat 
FOR Index=5 TO 11 STEP 2 
FOR Jindex=10 TO 30 STEP 20 
READ Lines 
PRINT CPS (Jindex,Index) ,Linet 
NEXT Jindex 
NEXT Index 
INPUT (PROMPT=CP$(10,15)&"Which would you like? ") Inputs 
Menu=VAL (Inputs) 
RETURN 


TITLE "COFFEE -- LIST PRINT ROUTINES" 
PEngin: D$="ENGIN" 

CALL OUTPUT (D$) 

RETURN 


PAdmin: D$="ADMIN" 
CALL OUTPUT (D$) 
RETURN 


PManufact: D¢="MANUF" 
CALL OUTPUT (D$) 
RETURN 


PMarket?:D$="MARKT" 
CALL OUTPUT (D$) 
RETURN 


TITLE "COFFEE -- ADD FILE RECORD ROUTINE" 
: this adds names to the appropriate list 
AddNames : 

GOSUB DeptMenu 

INPUT (PROMPT=CP$(10,15)&"Add to which department"®& 
i " (number)? ") Inputs 

Menu=VAL (Input) 

ON Menu GOSUB EngOpe-AddOpe-MarOpe -ManOpe ELSE 
. GOTO AddNames 
NameIn® INPUT (PROMPT=CS$(1)8&CP$(10,5)&"Name for " 
‘ &Depts&" list? (Last name first) "&CP$(10,6)) Names 

Key$=Names 

WRITE (LFN=1,KEY=Key#,ERL=DupeName) Names 
AdTst: INPUT (PROMPT=CP$(10,7)&"Add another name to " 
‘ &"this list? (Y or N) ") Inputs 

IF T#="Y" THEN GOTO NamelIn 

IF T$<>"N" THEN GOTO AdTst 

CLOSE (LFN=1) 
LstTst: INPUT (PROMPT=CS#(1)&CP$(19,5)% 
. “Add to another department’s list? " 
* &" CY or N) ") Inputs 

IF T$="Y" THEN GOTO AddNames 

IF T# NE "N" THEN GOTO LstTst 

RETURN iback to main logic 
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DupeName : 
IF IOERR=32 THEN 
PRINT CS$(1) -CP$(10,5),"Name (key) duplicates "& 
* "the following?” 
READ (LFN=1,/KEY=Key) InNames 
PRINT CP#(10,6) > InNames ,CHRS (7) 
INPUT (PROMPT=CP$(190,10)&"Type carriage return’®& 
“ "to continue ") Inputs 
GOTO NameIn 
ELSE 
ERROR IOERR 
ENDIF 


TITLE "COFFEE -- DELETE RECORDS ROUTINE" 
H this deletes names from lists 
Of fNames: 
GOSUB DeptMenu 
INPUT (PROMPT=CP$(19,15)&"Delete from which"®& 
: " department (number)? ") Inputs 
Menu=VAL (Inputs) 
ON Menu GOSUB EngOpe,AddOpe -MarOpe ,ManOpe ELSE 
s GOTO OffNames 
NameOut: INPUT (PROMPT=CS$(1)&CP$(10,5)& 
. "Delete what name from "&Deptsé 
* "list? (Last name first) "&CP$(19,6)) Names 
Key$=Names 
READ (LFN=1,KEY=Key$ -MODE="R" ,ERL=PartKey -EOF=NameOut) 
* InName$ 
NCheck: INPUT (PROMPT=CP$(10,14)& 
A "Name found is "&InName$&". "&CP$(10,15)% 
. "Is this correct (Y or N)? ") Inputs 
IF T#="Y" THEN DELETE (LFN=1) 
NTst: INPUT (PROMPT=CS$(1)&CP$(10,5)%& 
e "Delete another name from the "& 
. Dept$&" list (Y or N)? ") Inputs 
IF T#="Y" THEN GOTO NameOut 
IF T#<>"N" THEN GOTO NTst 
CLOSE (LFN=1) 
DTst: INPUT (PROMPT=CS$(1)&CP$(10,5)& 
“ "Delete from another "& 
° “department’s list (Y or N)? ") Input% 
IF T#="Y" THEN GOTO Of fNames 
IF TS<>"N" THEN GOTO DOTst 
RETURN 


PartKey:READ (LFN=1-KEY=Key% -MODE="S") InNames 
GOTO NCheck 


TITLE "COFFEE -- ADD AND DELETE ROUTINES’ SUBROUTINES" 
H these print the department menu, open files 


DeptMenu: 
PRINT CS#(1) -CP(10,5),"1) Engineering", 
7 CP$(10,7)-"2) Administration", 
+ CP$(10,9) -"3) Marketing", 
si CP$(1@,11),"4) Manufacturing” 


RETURN 


COFFEE 


EngOpe: 
AddOpe: 
MarOpe: 


ManOpe: 


OPENER: 


TITLE 


APPENDIX A 


Dept $="Engineering" 
O$="ENGIN” 
GOTO OPENER 


Depts="Administration"” 
D$="ADMIN" 
GOTO OPENER 


Dept$="Marketing" 
D#="MARKT" 
GOTO OPENER 


Dept$="Manufacturing” 
D#="MANUF " 


OPEN (FILE=0%,LFN=1 ,OPT=Z ,ORG="I") 
RETURN 


"COFFEE -- FILE ALLOCATION ROUTINE AND ENDIT" 
this is a startup piece, to set up files 


INITIATE: 


INPUT (PROMPT=CS$(1)&CP$(10,/5)&"This option is only " 


m &"used to allocate the files"&CP$(10,4)&" 


a 


the first " 


&"time the program is run."&CP$(10,7)&"Are you sure " 


~ &" you want to continue? (Y or N) "&CHRS(7)) Inputs 


ENDIT: 


TITLE 


IF Input$="N" THEN RETURN 

IF Input® NE "Y" THEN GOTO INITIATE 

ALLOCATE (FILE="ENGIN" »LFN=1 »,NREC=200,RECLEN=50, 
RECFMT="F" ,ORG="I" ,-KEYLEN=15) 

ALLOCATE (FILE="ADMIN"LFN=3,NREC=200 ,RECLEN=50, 
RECFMT="F",0ORG="I" ,-KEYLEN=15) 

ALLOCATE (FILE="MARKT" LFN=5 ,-NREC=200 ,RECLEN=50, 
RECFMT="F",ORG="I" ,KEYLEN=15) 

ALLOCATE (FILE="MANUF",LFN=7 ,NREC=200 ,RECLEN=590, 
RECFMT="F" ,ORG="I" ,-KEYLEN=15) 

RETURN 


CLOSE (LFN=@) 
END 


"COFFEE -- OUTPUT SUBROUTINE” 


SUB OUTPUT (D$) 


DIM D8 (1) 
DIM Key#(15) FIXED,Line$(50) ,Headers$ (5Q) 
DIM Dept$(20) -Holder$ (50,43) 


DS dept file name 

Keys ISAM file key 

Lines takes line from file 

Holders holds partial page-full of lines 
Header % holds page headers 

Depts holds department name 

PageNumber counter for pages of printout 
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¢ ) OPEN (LFN=1,FILE=D%,OPT=2,ORG="I") 


IF DS="ENGIN" THEN Dept$="Engineer ing" 
IF D$="MARKT" THEN Dept$="Marketing” 
IF D$="ADMIN” THEN Dept$="Administration"” 
IF D#="MANUF" THEN Dept$="Manufacturing" 
Key$=" ” 
Line$=" " 
Header$=" " 
PageNumber=0 
FOR I=1 TO 43 
Holder$(1,I)=Key% 
NEXT I 


| HdDat: DATA "DURANGO SYSTEMS MONTHLY COFFEE PAYMENT LIST", 
"Please make checks payable to Durango Systems Inc.”, 
"Please cross out your name and mark ""PAID""", 

“and pass this list to another person on it.", 

"If you wish your name removed from this list,", 
"cross off your name and mark ""DELETE""", 

"and pass the list to another person on it." 


> + FF Be & 


OutLooptREAD (LFN=1,KEY=Key$,EOF=ELoop) Holder#$(1,1) 
WRITE (LFN=@) FFS,LFS(3) 
Cy PageNumber =PageNumber+1 
RESTORE HdDat 
READ Headers 
WRITE (LFN=@) Header%,TABS(1) -Headers 
FOR I=1 TO 6 
READ Headers 
WRITE (LFN=@) Headers 
NEXT I 
WRITE (LFN=®@) LF#(3) -Dept%,TABS(1) Depts 
WRITE (LFN=0) "Page" ,PageNumber -LF$(3) 
FOR I=2 TO 43 
READ (LFN=1,KEY=Key%,EOF=EndILoop) Holder#(1,I1) 
NEXT I 
EndILoop: 
FOR I=1 TO 43 
WRITE (LFN=@,CARR=9) TABS(1@) -Holder#(1,1I) 
READ (LFN=1,/KEY=Key%,EOF=NxtI) Lines 
WRITE (LFN=0) TABS(65) -Lines 
J=1 
NxtIs IF J=@ THEN WRITE (LFN=@) 
J=O 
NEXT I 
GOTO OutLoop 
ELoop:s CLOSE (LFN=1) 
EXIT 


oY END 
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TITLE "REFERENCE -- MAIN LOGIC" 
: THIS PROVIDES A CONCORDANCE BASED ON A SPECIFIED STRING 


GOSUB INITIALIZE idim and initialize variables 
GOSVE GETNAME finput Ffilename,string,open files 
GOSUB READWRITE iread file,write scratch;close ‘am 
GOSUB ENDIT iclose up and get out 


' external subroutine OUTPUT does printing 


TITLE "REFERENCE -~ INITIALIZE" 
H THIS DIMs VARIABLES AND INITIALIZES 
INITIALIZE: 


DIM Line$(225) FIXED-Position#$(3) BASED, 
S LineNumber$(4) BASED ,Message#(217) BASED 
DIM File#(10) -String$ (80) , Inputs (8d) 
H Files name of input file 
} UnitNumber disk unit bearing file 
H Strings name of sought string 
H Lines linenumber&position&program line 
H made up of these three: 
H LineNumber $ physical line number 
' Positions print position code 
i Messages holds headers and then program line 
' Position converts position code to numeric WY 
H Inputs variable length, holds input line 
! Compares single character, holds leftmost 
! character of Strings 
H LineLength length of Input% 
1 Stringlength length of Strings 
H | VarLet indicates whether single character 
H sought string is letter or varjable 
! I index variable used in loops 
H RecordNumber counter, records from input file 
H LineNumber line numbers, each page of printout 
' PageNumber page numbers of printout 
; Question marker for variable tests 
H LL 1 left of Compare in variable test 
H RS 1 right of Compare, variable test 
1 SUBROUTINE (OUTPUT) VARIABLES 
i ARGUMENTS = all same as above 
H Lines 
' LineNumber $ 
H Positions 
H Message? 
! PageNumber 
' LineNumber 
H Files 


Strings oF) 
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Se Se ee ee eee ar ee oar 


a Lineg=" " iset to bianks 
BASE LineNumber$ AT Line(1) 
BASE Position AT Lines(5) 
BASE Messaget AT Line$(8) 
VarLet=9 
Recor dNumber=@ 
LineNumber=47 ‘cause eject,header on ist page 
PageNumber=90 
RETURN 


TITLE "REFERENCE -~- INPUT AND FILE ACCESS PREP" 

this inputs filename and sought string: 

checks if single character sought string is 

a variable or a letter, opens input file and printer 


OQ) -- -- -- 


ETNAME : 
PRINT CS$(1) ,CP$(10,5) ,"REFERENCE” 
PRINT CP#(10,6),"This is a cross-reference program" 
PRINT CP$(10,7),"What input file do you want?" 
INPUT Filet | 
PRINT CP$(10,9);,"What disk unit is it on?" | 
INPUT UnitNumber 
PRINT CP#(10,11),"What string do you want " 

s &"to cross-reference? " 
INPUT String* 
PRINT CP$(10,15),"Do you want to make any changes?" 
INPUT Messages 

Cy IF Message$(1#1)="Y" THEN GOTO GETNAME 


PRINT CS 

Compare$=String#(1i71) 

StringLength=LEN (Strings) 

IF Stringlength=1 THEN 

VTEST® PRINT CS#,CP$(10,-5),"Is this a letter or a variable?” 

INPUT Messages 
IF Message$(131)="L" THEN VarLet=1 
IF Message$(171)="V" THEN VarLet=2 
IF VarLet=@ THEN GOTO VTEST 


PRINT CSS 
ELSE 

VarLet=1 
ENDIF 


H open input file 

OPEN (LFN=2,FILE=Files,OPT=0_ UNIT=UnitNumber ) 
H open printer, set small font 

OPEN (LFN=@) 

WRITE (LFN=@) CS$(2) 


RETURN 
TITLE “REFERENCE -- READ-WRITE-SORT SECTION" 
READWRITE: 
RecordNumber=RecordNumbertl 
co PRINT CP#(10,5)-"Processing line number” »-RecordNumber 
READ (LFN=2,MODE="S",EOF=EndReadlLoop) Inputs 


LineLength=LEN (Input$) -StringLength+1 
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‘we use this for our read loop, using a single character 
‘comparison, so worstcase, our sought string is at the 
iright end of the input line, we need check to the 
length of the sought string minus one (so we get the 
‘first character) or, -—(StringLength-1), which 
iis -StringLength+l 
FOR I=1 TO LineLength 
IF Input$(I71)=Compare$ THEN ON VarLet GOSUB 
LETTER; VARIABLE 
NEXT I 
GOTO READWRITE tloop until end of file 


LETTER: 
iwe got a single character match, check full string 
IF Input$(I#StringLength) =Strinas THEN 


LineNumber $=Recor dNumber 


Position#=91-I iwe want our string at col 93 
Message%=Inputs 
CALL OUTPUT (Lines -PageNumber ,LineNumber ,File%,String$) 
ENDIF 
RETURN iback to comparison loop 


VARIABLE: 
H if we’re here, we know we have a match 
but is it our variable or is it a letter in a word? 
Question=0 imarker for left and right tests 
if Q=2 then its a variable, otherwise no a) 


1 
H test position to left of Compares first 
IF I=1 THEN 
Question=Question+tl 
ELSE 
L$=Input$(I-1371) 
IF L&® LE CHR#(32) OR L$="&" OR L$="(" OR 


| 7 (L® GE CHR$(42) AND L® LE CHRS(45)) OR L#="/" OR 
4 (L$ GE CHR$(59) AND L$ LE CHR$(42)) OR 
7 L$="\" OR L® GE CHRS(123) THEN Question=Questionti 
ENDIF 


' now test to the right of Compares 
IF I=LEN( Inputs) THEN 
Question=Question+1 , 
ELSE 
R$=Inputs(I+171) 
IF R@ LE CHR$(32) OR R$="&" OR (R® GE CHR#(41) AND 


“ R$ LE CHRS(45)) OR R$="/" OR RE="F" OR 

. (R$ GE CHR$(59) AND R# LE CHR#(62)) OR 

* R$="\" OR RB GE CHR$(123) THEN Question=Question+l 
ENDIF 


IF Question=2 THEN 
LineNumber $=RecordNumber 
Position$=71-I 
Message$=Inputs WwW 
CALL OUTPUT (Lines -PageNumber ,LineNumber »File$,Strings) 
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ENDIF , 

RETURN _ iback to comparison loop 
EndReadLoop: 

RETURN iback to main logic 


TITLE "REFERENCE -~- ENDING ROUTINE" 


ENDIT: CLOSE (LFN=@) ‘close printer 
CLOSE (LFN=2) iclose input file 
PRINT CS$,CP$(10,5) ,"End of concordance program" 
END 


SUB OUTPUT (Line ,-PageNumber ,LineNumber -File$,String$) 
DIM Line#(1) -Position#$(3) BASED 
DIM LineNumber$(4) BASED Message$(217) EASED 
BASE LineNumber$ AT Lines$(1) 
BASE Positions AT Line$(5) 
BASE Message AT Line$(8) 
Position=Position$ 


IF LineNumber=47 THEN! new page, write header 
PageNumber=PageNumber+1 
LineNumber=1 
WRITE (LFN=@) FFS,LFS(2) ,-TABS(1) ,"REFERENCE", 

‘i TABS (1) ,"REFERENCE" 

WRITE (LFN=@) TABS(1),-"INPUT FILE: ",Filet 
WRITE (LFN=@) TABS(1),-"ITEM REFERENCED: ",Stringt 
WRITE (LFN=@) TABS(1),"PAGE NUMBER!” ,PageNumber -LF%(3) 
WRITE (LFN=0) TABS(1)-"LINE NUMBER",TABS(1),; 


‘i "LINE NUMBER" ,TABS(9@) »"PROGRAM LINE” ,TABS(9@) - 
‘ "PROGRAM LINE" -LFS 
ENDIF 


WRITE (LFN=0) TABS(1) ,-LineNumber$, TABS (Position) , 
Messages - TABS (90) ,Strings 
above writes line number at left column 
writes program line centered on sought string 
and boldfaces sought string (starting in col 99) 
LineNumber=LineNumber+1 
EXIT 
END 
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APPENDIX B 
DISKETTE FILE STRUCTURES 


B.0 GENERAL 


F-85 on-line mass data storage in the standard system consists of two integral diskette 
drives, single or double sided. Optional additions include two additional diskette drives 
mounted in the auxiliary dual disk drive (Durango part number 8705 or 8715), which 
are the same as the integral drives as far as storage and user procedures are concerned, 
and the fixed disk drive option (part number 8730), which is discussed in Subsection 
B.2 below. 


B.1 DISKETTE ORGANIZATION 


Physically, the 54" minidiskettes are organized into 77 concentric tracks per diskette 
side, numbered 0 to 76. The diskette electronics divide each track into 12, or 24 
equal sectors, 12 on each side. Each of the twelve or twenty four sectors are 
referenced from an index hole in the diskette that is used to indicate to the controller 
electronics the beginning of the first sector on the track. Each sector within the 
track is identified by a special "header" data area at its beginning. The header contains 
the sector's individual address as well as other information used by the controller 
electronics. 


When a "factory fresh" diskette is to be used by the system, it must first have all 
the sector headings written onto the medium. This function is called "formatting" the 
diskette and is performed by the FORMAT system utility. 


The data space available in each sector is 512 byte locations. Each track therefore 
has a maximum formatted capacity of 512 X 12 or 6,144 bytes, or 512x24 or 12,288 
bytes, with a total diskette capacity of 473,088 bytes per side. 

Figure B-1, Minidiskette Organization 
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To prevent inadvertent writing of data over adjacent sector headers, the diskette 
controller performs data transactions with the media in fixed blocks of 512 bytes. 
There are 924 blocks on a single-sided diskette, numbered 0 to 923 for single side, or 
0 to 1847 for double sided. Since having to perform all user data transactions with 
the diskette system in fixed 512 byte blocks would impose severe limitations in logical 
data organizations, a means of interfacing the logical to the physical is necessary. 


The DX-85M file manager functions as a translator between the program logical data 
organization requirements, and the controller electronics requirements. The sector by 
sector data transactions with the diskette system thus become transparent to the 
programmer. 


Figure B-2, Simplified Diskette System Block Diagram 
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A file is allocated on the diskette as a group of contiguous sectors. Allocation consists 
of writing a directory record for the file in the $DIRECTORY file, which occupies 
the first 16 blocks (numbered 0 through 15) of the diskette. 


$DIRECTORY is a fixed record length file of 128 records of 64 bytes each. The first 
record holds the diskette volume information. The second reeord holds the record for 
the $DIRECTORY file itself. There can therefore be a maximum of 126 other files 
on a diskette, each file's directory information being stored in a record of SDIRECTORY. 
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Each record of $DIRECTORY contains the following data: 


Byte 1 Record status code: 
V = volume header 
A= active file 
B = inactive file 


Bytes 2-11 Filename: up to 10 characters, blank-padded on the right. 


Bytes 12-16 BOE (Beginning Of Extent): the first block of space allocated 
to the file, five digits with leading zeros. 


Bytes 17-21 EOE (End OF Extent): the last block allocated to the file, 
five digits with leading zeros. 


Bytes 22-29 EOD (End Of Data): the next block and byte available for 
data in the file. Data will be added to sequential files 
beginning at the EOD. EOD consists of eight digits, the 
first three of which specify the byte, the next five the block 
number, each zero-padded on the left. 


Byte 30 Type: the type of file; legal types are: 
system bootstrap 

system program file 

STAR BASIC program (source) files 
STAR BASIC compiled (object) files 
data files (random or sequential) 
ISAM index files 


ez spypounr 
nouou to wou ou 


M= ISAM master (data) files 
Byte 31 RECFMT (Record Format): legal formats are: 
F = fixed record length 
V = variable record length 
I = ISAM index file record format 
Byte 32 Protect: write protection status: 


P = write protected 
(blank)= not write-protected 


Bytes 33-35 RECLEN (Record Length): the record length of fixed length 
record files only. Range is 1-512, 3 digits zero padded on 
the left. 

Bytes 36-41 Date: six characters. If set by a DATE statement in STAR 


BASIC, the date is given in the form MMDDYY (MM=month, 
DD=day, YY=year). 


Bytes 42-64 Reserved for future use (blank). 


B.1 Diskette Organization APPENDIX B 


Internally, files consist of one or more records. Records are logical elements of a 
file that contain data relating to a specific item (i.e., payroll data about a specific 
employee). The file manager supports two kinds of records, fixed and variable length. 


Figure B-3, Fixed and Variable Length Records 
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Fixed and variable length record files vary in three important respects: whether they 
must have a standard record length throughout, where the record length is stored, and 
what the maximum length of a record can be. 


Fixed length record files (record format "F") must have all records the same length. 
The length of each record is stored in the file's directory listing. Records must be 
in the range 1-512 bytes. 
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Variable length record files (record format "V") may or may not have records of 
constant length. The length of each record is stored in a one byte record header 
attached to the record. This header is transparent to the STAR BASIC programmer, 
however, as it is automatically accounted for by the ALLOCATE, OPEN, READ and 
WRITE routines. Range of variable length records is 1-256 bytes (on the disk) or 0-255 
(as far as STAR BASIC is concerned). 


B.1.1 File Access Methods 


There are four types of disk access under STAR BASIC: sequential file access, random 
file access, ISAM (Indexed Sequential Access Method) file access and ABSOLUTE disk 
access. 


Sequential file access is by record order. Files are declared sequentially organized 
(ORG="S") in ALLOCATE and OPEN statements. Sequentially organized files may be 
read or written only in sequential mode (MODE="S"), in top to bottom record order. 


Random file access allows any given record to be accessed, by record number. Randomly 
organized (relative record) files (ORG="R") may be accessed sequentially (MODE="S") 
by record number order (which is essentially by record order, skipping blank records) 
or randomly (MODE="R") by specifying the record number. 


ISAM file access allows access by index key. ISAM files consist of a master data file 
and an index file containing the keys to the data file. ISAM files must be ALLOCATE'd 
and OPEN'ed as ISAM files. They can be read and written sequentially (MODE="S") 
by key order, or randomly (MODE="R") by key value. 


ABSOLUTE disk access ignores the file and record organization of the disk and largely 
bypasses the system file manager. ABSOLUTE disk access instead reads or writes a 
block of 512 bytes, by sector number. Data protection and interpretation is left 
entirely to the STAR BASIC program. 


Sequential access 


Sequential file access may be done on "F" or "V" files. Sequential file access is 
declared when the file is OPEN'ed. At that time the access option must be declared: 
read only, rewrite (from the beginning), write-extend (add to the end). The read only 
and write-extend options may not be used if the file has been open random access 
update, because this sets the end of data pointer in the file's directory listing to the 
end of file (see below). 


Sequential file access is buffered: the system reserves a 512 byte buffer for each 
open sequential file (see Subsection 1.1 in the main text). This can speed sorts and 
other data manipulations by minimizing disk accesses. 


Files open sequential access may be read or written only sequentially ("S" mode); an 
attempt to read or write randomly ("R" mode) is an I/O error. 
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Sequential files have two other special characteristics not true of random or ISAM 
files, both concerning their length. When an ORG="S" (organization=sequential) file is 
ALLOCATE'd, if the record length (RECLEN) and number of records (NREC) control 
groups equal zero, the file will be allocated across the largest open space available 
on the disk. Likewise, a file which is OPEN ORG="S" can be CLOSE-truncated (OPT=2). 
This truneates the file at the last block containing active data (the block number 
recorded in the end of data field). 


These special characteristics make sequential file access valuable in several specific 
ways: 


Free write: A data file of unspecified length can be written quickly as 
a sequential file, as follows: 

ALLOCATE format "F", organization "S", number 
of records, 0; length as desired; this takes the 
largest free space available on the disk. 

OPEN organization "S", access option 1 (rewrite); 
this grants buffering for a fast, sequential write. 

WRITE all records sequentially, making each 
the same length (record length declared in 
ALLOCATE). 

CLOSE truncate (OPT=2) to trim unused space 
from file. 

OPEN organization "R", access option 3 (update); 
this does not grant buffering, but does allow 
reading or writing any record by record number. 


Long term storage: A data file which will not be accessed frequently and which 
will always be either added to or read from the beginning 
(as a monthly report of daily transactions would be, for 
instance) would be allocated as a sequential, "V", file. By 
opening it each time as a sequential file option 2 (write- 
extend), records would be added to the end of the file until 
the time came to read it. Records could vary in length, 
depending on the data to be included. When the file is 
complete (at month-end, say), it could be CLOSE-truncated 
to save space while it is being preserved for later use. 


Random access 


Random file access may be done on "F" format files only. Random file access is 
declared when the file is OPEN'ed. At that time, access option 3 (update) must be 
declared, since this is the only legal access option for files open as random organization. 
Update mode allows reading or writing, sequentially by record number order, or randomly, 
by specifying a record number. 


Opening a file with the update access option sets the end of data pointer in its 
directory listing to the end of file. This is done because records may be written 
anywhere in the file—record 1 could be written, then record 35, then record 72, and 
so on; record 2 might never be written and thus could contain nonsense. 


Random file access is not buffered. Each READ or WRITE statement is a disk access. 
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Random file access has several advantages which make it useful for specifie applications. 
Because data can be read or written either randomly or sequentially, random access 
files are useful for data storage where frequent reference and rewriting are likely. 
Any single record can be read, written or rewritten, or the entire file can be accessed 
in record order. 


In addition, random access file records can be larger than sequential access file records. 
At the same time, they are somewhat more space efficient in one respect: the record 
length is recorded only once, in the file's directory listing, so the extra one byte/record 
overhead of sequential files is avoided. 


However, random access files are somewhat less efficient in space in another respect: 
since sequential access file records can vary in length, and since sequential access 
files can be CLOSE-truncated for long term storage, sequential files can be more 
densely packed with data then is possible in many applications with random files. 


The usefulness of random access files is also somewhat overshadowed by the advantages 
of ISAM. Since ISAM sorts its records by key value, ISAM is particularly useful where 
a sorted order, or cross-reference order(s), are important. 


ISAM access 


ISAM access files must be ALLOCATE'd as ISAM organization (ORG="I") and record 
format fixed (RECFMT="F") and the key length (KEYLEN) must be specified as well 
as the record length and number. 


ISAM files are two linked files, an index file of keys to the master, and a master 
data file containing the data records. The index file is record format "I": the first 
block contains file control data, each other active block contains an ordered list of 
keys and pointers. ISAM index files can be accessed only through the ISAM file 
manager. 


ISAM data files are a special case of record format "F". Each record (on the disk) 
contains a keylength header, a copy of the key to the record (both header and key 
are transparent to STAR BASIC), and the data record. Data records can be up to 
512 bytes long, so the physical record may be up to 537 bytes long. 


ISAM data files can be accessed normally through the ISAM file manager. If the 
records are short enough, they could also be accessed sequentially or randomly; however, 
if anything but a sequentially accessed read were attempted, the ISAM data file would 
be inaccessible to ISAM and the linkage between index and data files destroyed. 
Non-ISAM access is therefore not reeommended. 


ISAM access is declared when the file is OPEN'ed (ORG="I"). ISAM access options 
are separate from the sequential and random access option numbers. ISAM access 
options are the result of four independent characteristics: Read-only or read-write; 
exclusive access or non-exclusive access; fast sort buffering, or not; record clearance, 
or no record clearance on opening. 
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Read-only/read-write: an ISAM file can be open only for reading or both reads 
and writes can be allowed. 


Exclusive/non-exclusive access: an ISAM file can be open exclusive access (only 
one user may open it) or non-exclusive access. In general 
operations involving the entire file (DATE, RENAME, 
CLOSE-delete) require exclusive access, to prevent one user 
from deleting a file another is updating, for instance. 


Fast sort buffering: all ISAM access is buffered. If fast sort buffering is chosen, 
disk writes will be minimized; if fast sort is not chosen, 
data will be written to disk upon every WRITE. Fast sort 
access can be faster in some applications, but carries a small 
amount of risk should power fail or an operator CODE LOAD, 
since part of the file may not yet have been written to disk. 
Fast sort is normally used for scratch files. 


Record clearance: when an ISAM file is opened records cleared, all records are 
deleted before access is granted. Exclusive access is required 
(and automatic) with record clearance. This option is nor- 
mally used with scratch files, to avoid the need to re-allocate 
them. 


ISAM files may be read or written sequentially (MODE="S"), by key order, or randomly 
(MODE="R") by key value. 


Because ISAM keys are ordered in the ASCII collating sequence, ISAM files are 
particularly useful for records used in sorted order. Efficient ISAM cross-reference 
files can be created by concatenating the new key with the old key—see Subsection 
2.12.6.in the main text. 


Becasue ISAM files can be read or written sequentially or randomly, and because the 
ordering is not restricted to the simply integer order of random access files, and 
because ISAM files have the speed advantage of system buffering (see Subsection 1.1 
in the main text), ISAM file access somewhat overshadows random access methods. 
However, both types of file access have distinct advantages in specific circumstances. 


ABSOLUTE disk access 


ABSOLUTE disk access bypasses the file and record organization of the disk entirely. 
Instead, a specified block of the disk is read or written directly. Since this procedure 
largely bypasses the system file manager, data interpretation and protection is entirely 
the responsibility of the STAR BASIC program if this type of access is used. 


There are 924 blocks of data, each 512 bytes long, on a single sided diskette. They 
are numbered, sectors 0 to 923. For the double sided diskette there are 1848 blocks, 
each 512 bytes long, sector numbers 0 to 1847. When a READ or a WRITE is performed 
with the ABSOLUTE=1 control group active, the REC keyword specifies the sector to 
be read or written. 


Data is manipulated in blocks of 512 bytes only. Because the file and record organization 
of the disk is ignored, this type of access can be useful in a few specific circumstances. 
However, since faulty manipulation of this type of access can result in destruction of 
data—even the directory of the disk could be destroyed if a WRITE changed blocks 
0-15 to an unacceptable form—ABSOLUTE disk access is not normally used. 
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Buli.2 Data Recording Formats 


Unless otherwise ‘specified, data is written to the diskette as a string of ASCII 
characters. There are no headers or termination characters added to the data records; 
responsibility for type matching is left to the STAR BASIC program. 


Data is stored on disk in four formats: ASCII string, ASCII numeric, internal and 
packed. 


ASCII string: String vatues are stored one byte per character in standard 
ASCII symbols (see Table 2-8). If an X format is used, the 
string length will be limited to the length of the X format 
string. 


ASCII numeric: Numeric values are stored as a string of ASCII characters 
up to 21 bytes long, as in a PRINT statement: a blank, a 
- if negative, a decimal point, up to 14 digits, the exponent 
marker E, a - if the exponent is negative, one or two 
exponent digits. If a 9 format is used, length will be one 
byte per 9 in the format string, each 9 holding one non-blank 
numeric character. 


Internal: One byte per I in the format string; the first I holds the 
exponent and sign, each additional I holds two digits recorded 
packed BCD (binary coded decimal). 


Packed: One-half byte per P in the format string, with a zero added 
on the right if there are an odd number of P's. Data is 
recorded packed BCD with no sign or exponent. 


Data which was written in ASCII string or numeric formats can be read back into 
variables freely, provided no non-numeric characters are read into numeric variables 
and that the resulting numeric values are within valid range. Data stored in internal 
(I) or packed (P) formats, however, must be read back in the same format or an I/O 
error will occur. 


B.1.3 STAR BASIC/D-BASIC File Comparison 


STAR BASIC uses substantially less overhead than D-BASIC in disk storage. D-BASIC 
adds a two byte length header to all strings and floating point numerics, while STAR 
BASIC does not; D-BASIC adds a one byte record terminator to all fixed length records, 
while STAR BASIC does not. 


D-BASIC differentiates between string data, floating point numeric data, and integer 
numeric data. STAR BASIC does not (in default modes) but does allow use of FORMAT's 
to change the storage mode of numeric data. 
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D-BASIC Output 


WRITE, RWRITE, IWRITE statements: 


string data 


numeric (floating point) 


numeric (integer) 


PRINT statements (sequential only): 


all data types 


Reeord overhead: 


Sequential files 


Random and ISAM data files 


STAR BASIC Output 
WRITE statements (not ABSOLUTE): 


string data 
numeric (floating point) 


default FORMAT 
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two byte header gives length of string, followed 
by the characters in the string, one per byte 
in ASCII code 


two byte header gives length, followed by 
numeric value; first byte of value gives 
exponent and sign of value, up to 7 more bytes 
hold digits in packed binary coded decimal 
(BCD) 


two bytes hold the value as a 16 bit binary 
number; the second byte is read first 


output is as a single string of ASCII code, using 
the same rules as video or printer output from 
a D-BASIC PRINT statement; no headers are 
added to the data field 


one byte header gives the length of the record 
which follows 


one byte terminator (FF) marks the end of each 
fixed length record 


stored one character per byte in ASCII code; 
no headers or terminators 


stored one character per byte in ASCII code, 
as in the STAR BASIC PRINT statement output: 
a leading blank, followed by a - if the value 
is negative, followed by the decimal point and 
up to 14 digits, followed by an E marking the 
exponent, followed by a - sign if the exponent 
is negative, followed by the one or two digit 
exponent 


eC) 
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9 FORMAT stored one character per byte in ASCII code, 
one digit (or decimal point or sign) for each 9 
in the descriptor 


I FORMAT stored in internal format: first byte holds 
exponent and sign, each subsequent type (up to 
7 more, specified by the number of I's) holds 
two digits in BCD 


P FORMAT stored BCD with no exponent or sign, one digit 
per P, two P's per byte; if deseriptor holds an 
odd number of P's, a zero will be added on the 
right to make an even byte 


integer see P FORMAT above 
Record overhead: 


sequential files one byte header gives the record length of each 
variable length record 


random, ISAM data files no header or terminator; length of record is 
stored in the file's directory entry 


B.2 14 INCH FIXED DISK FILE ORGANIZATION 


The 14 inch fixed disk file organization is divided into two categories. The first 
category has a 12 megabyte and a 24 megabyte drive formatted with a 1:1 interleave. 
The second category has a 12 megabyte and a 24 megabyte drive formatted with a 
15:1 interleave. The difference between the two is that the 15:1 interleave 24 megabyte 
drive is used as two 12 megabyte drives in the same package. This gives two directories 
in the same package. 


The 1:1 interleave 12 megabyte 14 inch fixed disk consists of 808 tracks organized in 
31 sectors of 512 bytes each. 48 tracks are reserved as alternates, and for a customer 
service engineering test area where known correction code defects and other test 
patterns are stored. The 761 (-1 BLOCK) tracks remaining for use hold 23,590 sectors, 
or 12.08 megabytes. 


The 1:1 interleave 24 megabyte disk doubles the size of the 12 megabyte disk, with 
1616 tracks, a 96 track alternate/engineering area, and 1521 (-1 BLOCK) tracks for 
normal use. Disk organization is the same, 31 sectors of 512 bytes per track, giving 
47,150 sectors and 24.14 megabytes for programs and data. 


The 15:1 interleave 12 megabyte 14 inch fixed disk consists of 808 tracks organized 
in 31 sectors of 512 bytes each. 48 tracks are reserved as alternates and for a 
customer service engineering test area. The 760 tracks remaining for use hold 23,560 
sectors or 12.06 megabytes. Each half of the 15:1 interleave 24 megabyte 14 inch 
fixed disk has the same capabilities as the 15:1 interleave 12 megabyte 14 inch fixed 
disk. 


B.2 14 Inch Fixed Disk File Organization APPENDIX B 


Except for the total size, and the number of alternate tracks available, the two 14 
inch fixed disk systems are treated identically by the system. The $DIRECTORY size, 
the number of files, the $SYSTEM system file, and so on, are the same on both 12 
and 24 megabyte systems, except for the 15:1 interleaved 24 megabyte is treated like 
two 12 megabyte drives. 


When accessing a 14 inch fixed disk drive the CONFIG.SYS file (refer to section 1.1) 
must contain the appropriate unit descriptor. Refer to table 1-1 of section 1.1 for 
the correlation of unit descriptor and disk type. 


With three exceptions (detailed below) the 14 inch fixed disk is treated as if it were 
a giant-sized diskette. All I/O statements are used in the same way with the 14 inch 
fixed disk as they are used with the diskette drives. Likewise, all system utilities 
work with the 14 inch fixed disk drive just as they do with the diskette drives. The 
three operational differences are as follows: 
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1) $DIRECTORY size: the $DIRECTORY file on the 14 inch fixed disk is 64 
blocks long, rather than 16 blocks, thereby allowing up to 509 user files 
(diskettes allow 126). 


2) $SYSTEM file: the 14 inch fixed disk contains a new system control file, 
$SYSTEM, which cannot be deleted. $SYSTEM is used by the file manager 
to record disk errors and retries for use by the 14 inch fixed disk utilities, 
and for scratch space for certain operations. 


3) 14 Inch Fixed Disk utilities: an analysis utility, HDANAL, and a format 
utility, HDFMT1, are specific to the fixed disk. These utilities are discussed 
in detail below. 


From the point of view of a STAR BASIC programmer, the significant difference 
between diskettes and 14 inch fixed disk is the possible size of files. Some examples 
of utility invocations and STAR BASIC program statements using the 14 inch fixed 
disk are given below: 


: BDUMP 4 17968 17970 
: EDIT * TEST.BAS/4 
: COPY/4 */1 TO /4 


ALLOCATE (LFN=3),FILE="TEST1",U NIT=4,IU NIT=4,ORG="I",NREC=500 
RECLEN=275,KEYLEN=15,RECFMT="F") 

OPEN (LFN=3,FILE="TEST1",OPT=7,UNIT=4,IUNIT=4) 

WRITE (LFN=3,KEY=KeyOne$) Record$ 

READ (LFN=3,KEY=KeyTwo$) Record2$ 

READ (ABSOLUTE=1,REC=23001,UNIT=4) Block$ 


In the example above, the first invokes the BDUMP utility from unit 0 to display 
blocks 17968 through 17970 on the 14 inch fixed disk (which is designated unit 4 
throughout these examples). The second invokes the EDIT utility (in large font sereen 
display) to edit a file called TEST.BAS on unit 4, the 14 inch fixed disk. The third 
invokes the COPY utility from the 14 inch fixed disk (unit 4) and calls for all active 
files from unit 1 to be copied to 4. 


The rest of the examples above are STAR BASIC program statements accessing the 
14 inch fixed disk as unit 4. A file called "TEST1" is allocated and opened and written 
to and read. The last READ statement reads block 23001 from the 14 inch fixed disk. 


14 Inch Fixed Disk Utilities 


Two utilities are specific to the 14 inch fixed disk: a special formatting program, an 
error analysis program. The formatting program, HDFMT1, is used only by customer 
service engineers and dealer representatives and is not available to users. The HDANAL 
analysis program is distributed on the system diskette. This diskette must be CODE 
LOADed to run these utilities, because they may run under a version of the DX-85M 
operating system, which is not directly compatible with the released DX-85M operating 
system. 
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HDFMT1, the 14 inch fixed disk format program, is used when a disk is installed to 
test all tracks and sectors and to write sector headers and special test patterns used 
by the analysis program. Because use of this program destroys all data on the 14 
inch fixed disk, its use is restricted to authorized service personnel. 


HDANAL, 14 inch the fixed disk analysis program, conducts a set of diagnostic tests 
on the 14 inch fixed disk. The analysis is read/write tests and does not affect existing 
files on the 14 inch fixed disk. If a hard disk error occurs, HDANAL warns the user 
of file damage and the file's backup copy must be restored to the disk before it may 
be safely used. 
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HDANAL - 14 Inch Fixed Disk Analysis Utility 


HDANAL, utility consists of two separate programs, FDDIAG and FDSCAN. The system 
utility runs under the DX-85M operating system. This utility is used to determine 
that the basic functions, of the disk, work properly and scan the disk for correctable 
or uncorrectable errors. It does this by performing the FDDIAG, to test the CE 
portion of the disk for correct data, and verifying the ability to read, write and seek. 
It then performs the FDSCAN, which scans the user portion of the 14 inch fixed disk 
and lists any errors it encounters. 


: HDANAL 


: system command prompt. 
HDANAL utility file name. 
After invocation, HDANAL returns the message: 


*#** HDANAL VERSION n— **** 
ONE MOMENT PLEASE. PROCESSING OCCURRING 


When the system has finished the processing the following message will be displayed: 
**#** HDANAL VERSION n~— **** 
THIS SYSTEM HAS THE FOLLOWING HARD DISK CONFIGURATION. 
TYPE THE NUMBER OF THE TALK ADDRESS 
FOR THE DISK YOU WANT TO TEST. 
TALK ADDRESS 0 CONFIG.SYS DESCRIPTOR (S) FX or HX. 
After the talk address is entered the following message appears: 
FDDIAG: RUNNING 
The cursor will also be visable on the screen, with no user input allowed. 


When FDDIAG starts to run the message shown below will be output to the printer. 


| 
**** DISK BEING ACCESSED HAS TALK ADDRESS 0 **** | 
CONFIG.SYS DESCRIPTOR (S) FX or HX | 


FDDIAG: RUNNING 
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If an error occurs during the FDDIAG, the utility will output the following message 
to the printer: 


—sn WARNING: DISK SYSTEM FAILURE saa 


FAILURE: failure type activity type 


TRACK snumber 
SECTOR snumber 
REL.SECTOR  :number 
HEAD snumber 


1. FAILING COMMAND :command name 
2 SERIAL POLL STATUS 


RECEIVED : number 

EXPECTED : number 
3. STATUS BYTES 

EXPECTED : number 

EXPECTED : number 
4. DATA 

RECEIVED : number 

EXPECTED : number 


ACTION: NOTIFY CUSTOMER SERVICE REPRESENTATIVE IMMEDIATELY 
** DO NOT ATTEMPT TO USE DISK SYSTEM ** 


NOTE: The above process continues until all data mismatches, if any, are documented. 
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SERIAL POLL STATUS: 


STATUS BYTES: 


DATA: 


one byte received and expected 
The status words received and expected 


The expected and received data, recorded 32 
bytes per line in hexidecimal code. 


When the FDDIAG is finished, with no errors, the screen will then display the following 


message: 


FDSCAN: RUNNING 


TRACK NUMBER nnnnn 


The track number is updated as the heads are stepped in. 


The HDANAL utility automatically procedes to FDSCAN if no errors are encountered 
in FDDIAG. The FDSCAN portion of the utility starts scanning the user portion of 
the disk only. If it finds an error it will display the following message: 


(UN) CORRECTABLE ERROR BLOCK number (number, number) STATUS nn nn on 


The error will be identified as correctable or uncorrectable. 


BLOCK number 


fs» (number, 


number 


STATUS nn nn nn 


A five digit block address 
A five digit track address 
A five digit sector address 
three, two digit status bytes 


This error message is displayed on the screen and output to the printer. When the 
FDSCAN has completed the error log block (#91), on all fixed disk units, is set to all 


zeros, then the prompt: 


HDANAL: COMPLETE 


Will appear on the screen indicating that the HDANAL utility is finished. 
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HDFMT1 - 14 Inch Fixed Disk Formatting 


The HDFMT1 utility is a diagnostic utility. It is used only by dealer representatives 
and customer service engineers. The diagnostic ROMs must be inserted before HDFMT1 
is invoked. 


HDFMT1 formats the 14 inch fixed disk, writing sector headers and other necessary 
data on the disk. It also performs a surface analysis on the disk and assigns alternate 
tracks if needed. It also writes a set of customer engineering tests patterns on the 
customer service tracks on the disk which are used to test Error Correction Code 
(ECC) response of the disk's electronics. 


HDFMT1 should not be run on a disk containing active data, HDFMT1 will destroy 
existing data. HDFMT1 cannot be run under normal user operating system: the special 
diagnostic system diskette and ROMs are required. 


definition: HDFMT1 invocation 
HDFMT1 /unit 


: system command prompt 
HDFMT1 utility file name 


/unit designates disk unit number (default is unit 0) 
unit is an integer in the range 0-5 


Before HDFMT1 is run on the 14 inch fixed disk the user must be sure the address 
switches located in the rear panel are in the correct position for configuration desired. 
Refer to address switch setting chart in Fixed Disk installation and power-up procedure 
(101026-001). 
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After invocation, HDFMT1 returns the message: 


*#** HDFMT1 VERSION n **** 
ONE MOMENT PLEASE. PROCESSING OCCURRING 


When the system has finished the processing the following message will be displayed: 


**** HDANAL1 VERSION n **** 
THIS SYSTEM HAS THE FOLLOWING HARD DISK CONFIGURATION. 
TYPE THE NUMBER OF THE TALK ADDRESS 
FOR THE DISK YOU WANT TO TEST. 
TALK ADDRESS 0 CONFIG.SYS DESCRIPTOR (S) FX OR HX. 


After the talk address is entered, the system will proceed. 


If the diagnostic ROMs have not been installed in the fixed disk drive, HDFMT1 gives 
the following message: 


DIAGNOSTIC ROMs NOT INSTALLED. FORMAT ABORTED 


This message is not given if diagnostic ROMs have been installed before HDFMT1 is 
invoked. 


If there are active files on the 14 inch fixed disk, HDFMT1 then issues this message: 


*##* ACTIVE FILES ON DISK TO BE FORMATTED. **** 
ANY OTHER KEY EXITS THE PROGRAM 


If an error is found within the $DIRECTORY area of the 14 inch fixed disk, HDFMT1 issues 
this message instead: 


**# DISK TO BE FORMATTED MAY CONTAIN ACTIVE FILES’ *** 
TYPE G TO CONTINUE. 
ANY OTHER KEY EXITS THE PROGRAM 


If a 'G' was returned to either of the active files prompts, or if there were no active 
files on the 14 inch fixed disk, the initialization message would be followed by three input 
prompts (issued one at a time - they are shown together here for easier reading): 


TYPE DISK LABEL NAME (10 CHARACTERS MAX) 
input appears here 
TYPE OWNER NAME (20 CHARACTERS MAX) 


input appears here 
TYPE THE DATE IN THE FORMAT MMDDYY 


input appears here 
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Input to each prompt must be terminated by a carriage return. There are two possible 
error messages at each of the three input points: 


ILLEGAL INPUT. TRY AGAIN 
TOO MANY CHARACTERS. TRY AGAIN 


Whether the input is too long or is otherwise illegal, HDFMT1 responds by issuing the 
appropriate error message and returning the input prompt again. 


After the disk label, owner name and date have been input, HDFMT1 issues this menu: 
HARD DISK FORMATTER 


1) FORMAT DISK 
2) BLANK DIRECTORY ONLY 


input appears here 
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A menu item is chosen by inputting its number. Input other than a 1 or 2 followed 
by a carriage return is ignored and the prompt is re-issued. 


If the second option is chosen, HDFMT1 will not format the disk or conduct surface 
analysis tests. It will only blank the directory of the disk and write the error log 
contained in the $SYSTEM file. If this option is chosen, a successful run will look 
like this on the video display: 


HARD DISK FORMATTER 

1) FORMAT DISK 

2) BLANK DIRECTORY ONLY 
2 
DISK BEING ACCESSED HAS TALK ADDRESS n 
INITIALIZING DIRECTORY AND WRITING ERROR LOG 
DIRECTORY WRITE COMPLETE 


After HDFMT1 terminates, other diagnostic programs may be run from the system 
prompt (the : ). However, only diagnostic programs may be run: other utilities and 
user programs require that a normal user system be CODE LOADed before they can 
be used. 


If the first option is chosen, a successful run will look like this: 


HARD DISK FORMATTER 
1) FORMAT DISK 
2) BLANK DIRECTORY ONLY 
1 
DO YOU WANT TO ENTER ANY TRACKS TO BE FLAGGED AS DEFECTIVE? 
(Y=YES) 
ENTER A TRACK NUMBER AT EACH '?' AND HIT RETURN. WHEN ALL 
TRACKS INPUT, TYPE 'E' AND HIT RETURN TO CONTINUE HDFMT1. 
DISK BEING ACCESSED HAS TALK ADDRESS n 
FORMATTING DISK 
TESTING ALTERNATE TRACK AREA 
TESTING CE TRACK AREA 
TESTING USER TRACK AREA 
WRITING CE TRACKS WITH PROPER DATA 
WRITING ALTERNATE TRACK MAP 
INITIALIZING DIRECTORY AND WRITING ERROR LOG 
FORMAT COMPLETE. BE SURE TO REMOVE DIAGNOSTIC ROMs. 


During the track tests the track number being tested will appear in the upper right 
hand corner of the screen. 


HDFMT1 first formats the disk, then tests the alternate track, customer engineering 
and user tracks, then writes the customer service tracks with their ECC check patterns 
and patterns of all 0's, all 1's, hexidecimal AA's, random data and worst-case bit-shift 
patterns, then writes the alternate track map in the $SYSTEM file and on the printer, 
then writes the directory and error log. 
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There are two possible alternate track messages on the printer. If no alternate tracks 
are assigned, the printer message is as follows: 

NO ALTERNATE TRACKS ASSIGNED 
If alternate tracks are assigned, there are two possible message formats. The first 
is used if an alternate track itself is found to contain errors. The second form is 
used if CE or user tracks are found to contain errors: 

ALTERNATE TRACK number FOUND BAD 

TRACK number MAPPED TO ALTERNATE TRACK alternate number 
Thus, an alternate track map with both alternate track errors and user track errors 
could look like this: 

ALTERNATE TRACK MAP 

ALTERNATE TRACK 773 FOUND BAD 

ALTERNATE TRACK 774 FOUND BAD 

TRACK 761 MAPPED TO ALTERNATE TRACK 801 

TRACK 762 MAPPED TO ALTERNATE TRACK 802 

TRACK 763 MAPPED TO ALTERNATE TRACK 799 
HDFMT1 writes the alternate track map both to the printer and to the last block of 
the $SYSTEM file. WwW 


HDFMT1 Error Messages 


Other than the input error messages noted above, HDFMT1 may issue one of the 
following: 


MORE ALTERNATE TRACKS NEEDED THAN ARE AVAILABLE. FORMAT ABORTED. 
The alternate track area has been exhausted and some user or CE tracks 
still require alternates. HDFMT1 aborts without finishing run; 14 inch 
fixed disk unit must be serviced or replaced. 

INITIALIZATION SHOWS ERRORS, STATUS = 41 
The fixed disk controller board returns an error status after a reset 
command has been issued by HDFMT1. HDFMT1 aborts; controller board 
and 14 inch fixed disk unit should be checked for faults. 

FORMAT COMMAND TERMINATED WITH ERROR, STATUS = 41 


Format command to disk fails, HDFMT1 aborts. Controller board and 14 
inch fixed disk unit should be checked for faults. 


ALTERNATE TRACK ASSIGNMENT SHOWS DISK ERROR 


Command to assign alternate track returns error; HDFMT1 aborts. Con- 
troller board should be checked for faults. 
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TRACK number FOUND BAD. THEREFORE, PRESENT DISK CANNOT BE USED. 
FORMAT ABORTED 


This message is issued when an error is found in tracks 0, 1, or 2, the 
directory and system file area. Since reassignment of a track in this 
area would degrade disk performance beyond allowable limits, any uncor- 
rectable error in this area is treated as a bad disk. HDFMT1 aborts, the 
disk unit should be returned to the factory for service. 


WRITE FAILS AFTER 3 RETRIES, TRACK number BLOCK number 
FORMAT ABORTED 


Error status returned during write in already-tested area (this normally 
would appear during a write to the CE area, the directory or the $SYSTEM 
file). HDFMT1 aborts, controller electronics and rest of 14 inch fixed 
disk unit should be checked for faults. 


WRITE LONG FAILS AFTER 3 RETRIES, TRACK number BLOCK number 
FORMAT ABORTED 


In a write-long, a 516 byte block is written, the last four bytes containing 
the ECC code. This error could only occur during writing of the CE 
tracks, which contain known ECC errors for use by other test programs. 

a) HDFMT1 aborts, the controller electronics and the rest of the 14 inch 
fixed disk unit should be checked for faults. 


YOU AREN'T GOING TO BELIEVE THIS BUT I COULDN'T READ LONG FROM THE 
DISK WITHOUT ERROR. FORMAT ABORTED. 


Like a write-long, a read-long reads a 516 byte block including four bytes 
of ECC. This error can occur if sectors 0 through 23552 all fail on 
read-long attempts after the normal test procedures are finished. The 
read-long attempt is made just before the CE tracks are written, to 
supply ECC data for modification. HDFMT1 aborts, controller electronics 
and the rest of the 14 inch fixed disk unit should be checked for faults. 


B.3 5 1/4 Inch Intergrated APPENDIX B 
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The 5 1/4 inch fixed disk drives are detailed in the chart below. The 5 1/4 inch fixed 
disk drives are treated the same by the system. The $DIRECTORY size and $SYSTEM 
file are identical. They are also the same as the other fixed disk options offered. 
When accessing the 5 1/4 inch fixed disk drive the CONFIG.SYS file (refer to section 
1.1 for the correlation of unit descriptor and disk type. 


TYPE A TYPE. B 
INTERLEAVE 8:1 8:1 
DIRECTORIES 1 1 
CAPACITY PER 
DIRECTORY 7Mb 7™Mb 
USABLE BLOCKS 
PER DIRECTORY 14008 14008 
CYLINDERS (USER) 
(TRKS.PER SURFACE) 206 206 
R/W HEADS 4 8 
TRACKS 824 1648 
SECTORS PER TRK. 17 17 
BYTES PER SECTOR 512 512 


The 5 1/4 inch fixed disk is treated as if it were a diskette; with three exceptions 
listed below. All I/O statements are used in the same way with fixed disk as they 
do with diskette drives. The three operational differences are as follows: 


L $DIRECTORY size: The $DIRECTORY file in the 5 1/4 inch fixed disk is #4 
blocks long rather than 16 blocks. This allows up to 509 user files. 


a $SYSTEM file: The 5 1/4 inch fixed disk contains a new system control file, 
$SYSTEM, which MUST NOT be deleted. $SYSTEM is used by the file manager 
to record disk errors and retries for use by the fixed disk utilities, and for 
scratch space for certain operations. 
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3. The 5 1/4 inch fixed disk utility IFANAL: IFANAL is discussed in detail on 
the following pages. 


IFANAL - 5 1/4 Ineh Fixed Disk Analysis Utility 


The IFANAL utility consists of two separate programs, IFDIAG and SCAN (read only). 
The system utility runs under the DX-85M operating system. The utility is used to 
determine that the basic functions of the 5 1/4 inch fixed disk work properly and scan 
the disk for correctable or uncorrectable errors. It does this by performing the IFDIAG, 
to test the CE portion of the disk for correct data, and verifying the ability to read, 
write and seek. It then performs the SCAN (read only), which scans the user portion 
of the disk and lists any errors it encounters. 


: IFANAL 


is the system prompt. 
IFANAL is the utility name. 
To invoke the analysis utility enter the name IFANAL in response to the system prompt. 
The following message will then appear on the screen: 
IFANAL VERSION n 
ENTER THE LETTER OF THE MODEL OF DRIVE YOU ARE TESTING 


MODEL NUMBER OF CYLINDERS NUMBER HEADS 
A (RMS509) 216 ; 4 
B (RMS518) 216 8 


Enter the letter of the model (type) in the computer, A, for a 7 megabyte, or B, for 
a 14 megabyte (2 directory). When the letter has been entered the system will then 
prompt for the disk unit number, as shown below: 


ENTER HARD DISK UNIT NUMBER YOU WISH TO TEST 


The number asked for here is the physical unit number. The 5 1/4 inch fixed disk in 
the computer should be unit 0, a 5 1/4 inch fixed disk auxiliary unit should be unit 
1. When the unit number is entered, the message shown below should appear: 


BOARD SELF TEST AND RESTORE TEST IN PROGRESS 
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This prompt means that the analysis testing has started. The tests mentioned in this 
prompt are tests for the drive controller PCB (board self test) and for the drive restore 
function. The first part of the test is the board self test. If an error is detected 
during this test the following message will be displayed: 


BOARD SELF TEST FAILS, IFANAL ABORTED 


The test does abort the analysis program and return to the system prompt (:). If no 
errors are detected the program continues to the restore portion of the test. If a 
restore cannot be performed properly the message shown below will appear: 


RESTORE COMMAND FAILS, STATUS xx,yy 


The "xx" and "yy" are the error status bytes. If there is no problem with the restore, 
the program will than proceed with the IFDIAG portion of the analysis and the following 
message will appear: 


IFDIAG IN PROGRESS 
READ PREWRITTEN DATA TEST 


There are four parts to the IFDIAG portion of the analysis test, they are; Read 
Prewritten Data Test, Write/Read Data Test, ECC Test, and Incremental Seek Test. 
As the tests are performed the title of the test will be displayed under the test just 
completed, as shown below: 


IFDIAG IN PROGRESS 
READ PREWRITTEN DATA 
WRITE/READ DATA TEST 
ECC TEST 

INCREMENTAL SEEK TEST 


If a data compare error is detected during the running of Read Prewritten Data, 
Write/Read Data or ECC Test, the following error format will be displayed on the 
CRT: 


IFDIAG IN PROGRESS 

(test name) 

COMPARE ERROR BLOCK n CYLINDER n HEAD n 

SECTOR n STATUS xx,yvy BYTE n RECEIVED nn EXPECTED nn 
DO YOU WISH TO PRINT THE DATA? 
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The test in progress at the time of the error will be named. The "n" following the 
descriptors will be a number corresponding to the block, cylinder, head, sector and 
byte. The "xx" and "yy" represent the error status and the "nn" will indicate what 
was received and what was expected to be received. A "NO" response to the inquiry 
to print the data aborts the test. A "YES" response to the question will output the 
data to the printer, as shown below, then aborts the test: 


(test name) 
COMPARE ERROR BLOCK n CYLINDER n HEAD n SECTOR n STATUS xx,yy BYTE 
n RECEIVED nn EXPECTED 


RECEIVED nn nn nn nn nn nn nn nn nn nn nn nn nn nn nn 


nn nn 
EXPECTED nn nn nn nn nn nn nn nn nn nn nn nn nn nn nn nn nn nn 


nn nnonn nn 
nn nn nn nn nn 


ETC. 


The received, expected output will continue until the entire error has been printed 
out. If a disk error occurs during the ECC test the CRT display will appear as follows: 


IFDIAG IN PROGRESS 

READ PREWRITTEN DATA TEST 

WRITE/READ DATA TEST 

ECC TEST 

ERROR ON READ BLOCK n CYLINDER n HEAD n 
SECTOR n STATUS xx,yy [EXPECTED nn,nn] 


DO YOU WISH TO PRINT DATA? 


All of the data for this test is the same as the previous tests. There is no received 
data recorded. The response to the question for printed data will have the same 
results as the previous tests, except for the [EXPECTED nn,nn] which is the expected 
status. The format for the printed error message will be as follows: 


ECC TEST 
ERROR ON READ BLOCK n CYLINDER n HEAD n SECTOR n STATUS xx,yy 
EXPECTED nn,nn 


The data printed has the same definition as the other tests, the difference is the 
EXPECTED status (nn,nn) is a two byte response, and found only in the ECC test. A 
disk error for the other tests will appear in the same format, except for the EXPECTED 
status which is only used for the ECC test. 
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When the IFDIAG portion of the analysis is complete, the SCAN (read only) will begin. 
The SCAN portion of the testing will be listed under the previous tests on the CRT 
as shown: 


IFDIAG IN PROGRESS SCANNING CYLINDER nnnnn 
READ PREWRITTEN DATA TEST 

WRITE/READ DATA TEST 

ECC TEST 

INCREMENTAL SEEK TEST 

SCAN IN PROGRESS 


The "SCANNING CYLINDER nnnnn" message will be updated as the scan test progresses. 
If an error is detected during the SCAN test the message shown below will appear on 
the CRT: 


ERROR IN READ BLOCK n CYLINDER n HEAD n 
SECTOR n STATUS xx,yy 


This error message has the same information as the IFDIAG error messages. The print 
out of the error message, shown below, also has the same meanings. The "n" represents 
a number and the "xx,yy" indicate error status. 


SCAN IN PROGRESS 
ERROR ON READ BLOCK n CYLINDER n HEAD n SECTOR n 
STATUS xx,yy 


When the IFANAL program has finished running, the following message will appear: 


IFDIAG IN PROGRESS 

READ PREWRITTEN DATA TEST 
WRITE/READ DATA TEST 

ECC TEST 

INCREMENTAL SEEK TEST 
SCAN IN PROGRESS 

IFANAL COMPLETE 


Upon completion of the analysis, the program will return to the system prompt (:). 
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APPENDIX C 
C.1 MULTI-USER PROCEDURES 
C.1.0 Overview 


Up to four additional terminals can be added to the multi-tasking F-85 through the 
four RS232 I/O ports of the multi-communications option. In addition to the multi- 
communications options and one or more external terminals, the following software is 
required for multi-tasking: 


1) DX-85M operating system 
2) STAR BASIC compiler 


3) RUN/RUNB runtime monitor (NOTE: Any time RUN Runtime 
monitor is referred to in Appendix C, it alludes to RUN or RUNB, 
whichever, was selected, RUNB requires expanded memory). 


4) One or more STAR BASIC programs designed for a multi-tasking 
environment, compiled by the STAR BASIC compiler 


The DX-85M multi-tasking operating system can be used in single or multi-user modes. 
All system utility use, including use of the COMPILE compiler, requires single user 
mode. All multi-user operations must be STAR BASIC programs, running under the 
RUN runtime executive. 


Multi-user mode is invoked by adding a control file name after "RUN" in the runtime 
monitor invocation. This control file defines the partitions, assigns a terminal to each 
partition and specifies the main program which will run in each partition. Control 
files are created through the use of the EDIT utility. Creation and use of control 
files is discussed in Subsection C.1.1. 


Occasionally a program will run using a partition control file, but only a single partition 
will be designated. This single-user partition is treated partially as single-user mode 
and partially as multi-user mode: a single partition is like single-user mode in that 
the RUN quit command can be used to return to the system command level (the : 
prompt), something which is not allowed if more than one partition is specified; the 
single partition is like normal multi-tasking mode in all other ways, including COMMON 
memory as specified in the partition, and the automatie chain to the main program 
specified in the partition if a carriage return is given to the * prompt after an abnormal 
program termination (see subsections C.1.1 and C.1.2). 


In each partition, the main program will normally be a "main menu" which calls other 
programs to perform assigned tasks. Whenever a STOP or END is reached in a 
subsidiary program, the RUN runtime executive will automatically return to the main 
program (main menu) assigned to that partition. If a STOP or END is reached in the 
main program, RUN will reinvoke it. If an abnormal termination occurs (an untrapped 
error), RUN will return the * prompt. Inputing carriage return will automatically 
return to the main program; however, if desired, RUN will respond normally to the 
debug commands, allowing a programmer to troubleshoot a program while other applica- 
tions run in the other partitions. The multi-user mode and the RUN runtime executive 
are discussed in Subsection C.1.2. 
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Sequential, random and ISAM files can all be shared by programs in different partitions. 
ISAM files also may be opened in exclusive access modes, denying access to any other 
program. Certain operations with ISAM files (RENAME, DATE, CLOSE delete) require 
exclusive access. The main console printer is always opened exclusive access. 


ISAM files also possess a record locking capability to prevent such things as two users 
rewriting the same record at the same time, or one user deleting a record which 
another user is reading.  Multi-tasking file use is discussed in Subsection C.1.3. 


Applications running in a multi-user environment require consideration of a number of 
factors in addition to those normally considered in application design. Since program 
size is limited (no program or subsidiary program can exceed the size of the partition 
to which it is assigned), applications running in a multi-tasking environment must be 
properly segmented, with an eye to the partition plan and the other applications which 
will run concurrently. 


Likewise, since several applications may need to manipulate the same files, each 
partition's program must be designed to avoid undesirably long waits for access to 
become available (giving the operator the option of choosing another activity after a 
certain amount of time has passed) and no program may cause a shared file to become 
permanently unusable by the other concurrent programs. 


In addition, some applications may need access to several files at once. Care must 
be taken to avoid the "deadly embrace", where each program has exclusive access to 
some of the files it needs, but not all, and neither (or none) will release what it has. 


Likewise, file and program security become more important in a multi-tasking environ- 
ment, since a number of operators may be active at a given time. These, and other 
considerations in planning applications to run in a multi-user environment, are discussed 
in Subsection C.1.4. 

C.1.1 Control File Use 


definition: partition definition line (in control file) 


T=terminal number C=number of common pages P=main program name F=number of files 


A M=number of pages of memory 
T=integer C=integer P=filename F=integer M=integer 


T=terminal integer designating the terminal to be assigned to the 
partition 
C=common integer designating the number of pages of memory 


assigned to common variables (maintained and avail- 
able to all external subroutines and all programs 
chained into this partition) 


ww 
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P=program file name of the main program (main menu) assigned 
to this partition 


F=files integer designating the maximum number of files which 
will be open simultaneously in this partition 


M=memory integer designating the number of pages of memory 
assigned to this partition (the size of the partition, 
in other words) 


A control file consists of one or more partition definition lines. Each line defines a 
partition, giving the RUN executive the information it needs to create and maintain 
the partitions (to a maximum of five) of the multi-tasking F-85. 


A partition is a segment of memory assigned to a user program set, overseen and 
controlled by the RUN runtime executive. Each partition may contain a Common 
area, a section of memory which is not cleared when a new program is chained into 
the partition. The common area is also accessible to all external subroutines attached 
to a program running within the partition. 


Each partition is assigned a terminal. Terminal 0 is the main console, while terminals 
1 through 4 are assigned to the external terminals through the multicommunications 
option. Naturally, many systems will not have the full five terminals available. 


Each partition is assigned a main program (main menu). RUN will automatically return 
to this program at any normal termination and will also return to this program upon 
receiving a carriage return after an abnormal termination (untrapped error). 


Each partition is assigned buffer use for the declared maximum number of files to be 
open at any one time. The declared maximum number of files in the partition is also 
the largest logical file number (LFN) allowed in that partition. A partition with a 
maximum of 5 files will use LFN's 0 through 5, 0 of course being the printer. 


A control file is created through the use of the EDIT utility. Each expression on each 
line of the file must begin with a control letter followed by an = sign followed by 
the appropriate integer or string, separated from the next expression by a space. There 
must be one line in the control file for each partition to be used in the multi-user 
applications. 


The control file is read by RUN upon RUN's invocation. The multi-tasking RUN 
invocation is as follows: 


: RUN control filename 
: RUNB control filename 


RUN will then read the control file designated and configure the F-85 as directed by 
the file. 
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Examples: 
file ALPHA 
=0 C=0 P=MAINCHAIN F=3 M=10 
=2 C=4 P=OTHERCHAIN F=9 M=15 
=1 C=2 P=MORECHAIN F=3 M=14 
file BETA 
T=3 C=0 P=ARPMEN F=4 M=36 
T=1 C=3 P=NRMEN F=10 M=18 
T=0 C=5 P=NPTMEN F=3 M=13 
file GAMMA 
=0 C=0 P=CTLMEN F=3 M=20 
T=1 C=2 P=APL1 F=3 M=15 
=2 C=1 P=APL2 F=3 M=21 
T=3 C=4 P=APL3 F=4 M=10 
T=4 C=2 P=APL1 F=3 M=15 


Memory Calculation 


The amount of memory needed to run a program is given at the very end of the 
program's compiler listing, where the number of pages of memory and the number of 
common pages needed are specified. The number of pages of common needed in a 
partition is the largest number of common pages required by any one of the programs 
which will run in the partition. 


The number of pages of memory needed in a partition is the number specified for the 
largest program which will run in the partition. In other words, if five programs are 
to run in Partition 1, the five program having the following memory and common 
requirements: 


Program 1: 15 pages memory, 4 pages common 
Program 2: 10 pages memory, 0 pages common 
Program 3: 5 pages memory, 5 pages common 
Program 4: 20 pages memory, 2 pages common 
Program 5: 13 pages memory, 2 pages common 


then Partition 1 will need at least 20 pages of memory and 5 pages of common. 
However, memory required (as shown on the compiler listing) includes 5 pages of stack 
space and other runtime overhead. Programs with very large string manipulations or 
a very large number of nested GOSUB's or subroutine or function calls may need 
additional stack space. If so, a runtime error (STACK OVERFLOW) will occur if the 
partition includes only the automatic 5 pages overhead. If this should occur, users 
should add pages to the memory requirement for the program in question. 
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631.2 Multi-User Runtime 


definition: RUN invocation (multi-user) 
RUNB invocation (multi-user) 


: RUN[/unit number] filename[/unit number ] 


: RUNB{/unit number] filename[/unit number ] 


NOTE: RUNB requires the 5MHz CPU and the Memory Expansion options to operate. 


To invoke the RUN/RUNB runtime executive in the multi-user mode, input RUN/RUNB 
after the system prompt (the colon :) followed by the name of a control file (see 
Subsection C.1.1 for control file creation and use). A / followed by an integer indicates 
the disk unit containing the file; default is disk unit 0. NOTE: Any reference to 
RUN in this manual, stands for RUN or RUNB, whichever the user has selected. 
If the control filename is omitted, RUN will come up in the single user mode, returning 
the * asterisk prompt. In the multi-user mode, RUN reads the control file and 
establishes partitions according to the file instructions. RUN immediately loads each 
partition's main program into that partition and begins running those programs. Each 
program will then sign on at its designated terminal. 


CAUTION: In RUN or RUNB the partition control file name should not begin with a 
number. A file name beginning with a number will be considered a COMMON memory 
specification and the run-time monitor will begin in single user mode. The COMMON 
will be allocated to the size indicated by the number at the beginning of the file 
name, up to the first non-numeric character. No error is reported. Thus, "RUN 66.M" 
would come up in single user mode with 66 pages of COMMON. 


Program Termination 


Normal termination of any program in a partition causes RUN to immediately load 
and run the main program for that partition. Since most main programs will be menus, 
the main menu for that partition would then appear on the terminal attached to that 
partition. Normal termination is via a STOP or END statement. When a control file 
is used, the STOP or END statement execution is much like executing a CALL CHAIN 
to the main program for that partition. Subsidiary programs which chain to another 
subsidiary program do not cause return to the main menu. 


Abnormal termination (by an untrapped error) causes RUN to give an error message, 
followed by the * asterisk prompt on the terminal assigned to the partition with the 
termination. Programs in other partitions will continue normally (unless, of course, 
they get an untrapped error as well). If a carriage return is input to the * prompt, 
RUN will return to the main program. For debugging purposes, RUN will also respond 
to the normal debug commands (display, breakpoints, GO, and so on). However, 
multi-tasking RUN will not respond to a QU (quit) command by returning to the system 
prompt (the :); instead, it will return an error message if QU is attempted. This 
disabling of the QU command is done to safeguard tasks which may be running in 
other partitions. (RUN with a single partition will respond to QU, however). 
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C.1.3.1 Call Environ Statements 


a 


When an error occurs during CALL CHAIN, STOP or END processing, any active ON 
ERROR TRAP in the calling (stopping) program will be activated. The program will 
execute the ON ERROR routine. 


Runtime Termination 


The RUN runtime monitor in multi-user mode will not perform the QUIT command or 
terminate unless a CODE LOAD or a CODE RESTART is performed on the console 
or the F-85 is turned off. CODE RESTART is a system debugging tool and should 
not be used in normal operation; if it is accidentally triggered, a TRAP and RST1 
EXEC message will appear—the operator should CODE LOAD and check ISAM files (in 
particular) for damage. 

Care must naturally be taken by the console operator not to CODE LOAD or turn off 
the F-85 while applications are running on other terminals. Programs for a multi-user 
environment should be designed to be in a safe state (all files closed, all data preserved) 
at a — menu. Optionally, a termination routine could be included in a partition's 
menu(s). 


C.1.3 CALL STATEMENTS 
3.1 CALL ENVIRON STATEMENT 


definition; CALL ENVIRON statement 


CALL ENVIRON(files, memory,common, terminal [,new terminal] ) 
CALL ENVIRON(numeric variable,numeric variable,ynumeric variable, 


numeric variable [,numeric variable }) 


A CALL ENVIRON statement consists of the words CALL ENVIRON, followed by four 
(optionally, five) numeric variables in parens, separated by commas. 


The CALL ENVIRON statement is used to read the line in the RUN control file which 
defines the partition within which the statement is used. Optionally, it can also be 
used to change the terminal assigned to the partition. 


The four (or five) parameters are used purely by their order in the list. The first 
returns the number of files allowed open in the partition (the F parameter from the 
control line); the second returns the number of pages of memory (M); the third returns 
the number of pages of common memory (C); the fourth returns the number of the 
terminal assigned to the partition (T). All parameters must be numeric variables. The 
first four will hold the values returned. 
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The optional fifth parameter changes the number of the terminal assigned to the 
partition. The value of the numeric variable becomes the terminal number assigned 
to the partition, after the other four parameter variables are filled. 


Examples: 
Partition A: T=0 F=3 C=0 M=10 P=MAINCHAIN 
Partition B: T=2 C=4 P=OTHERCHAIN F=9 M=15 
Partition C: T=1 C=2 P=MORECHAIN F=3 M=14 
In partition A: CALL ENVIRON(A1,A2,A3,A4) 
would return: A1=3 

A2=10 

A3=0 

A4=0 
In partition B: CALL ENVIRON(F,M,C,T) 
would return: F=9 

M=15 

C=4 

T=2 


Partition C could interrupt partition B with a message with a program like this: 


NewTerm=2 

A$="Hello" 

CALL ENVIRON(F,M,C,T,NewTerm) 
PRINT A$ 

CALL ENVIRON(F,M,C,X,T) 


Of course, if partition B was in the middle of the main menu, the word Hello suddenly 
appearing at the current cursor position could be disruptive. A worse case is possible 
if the operator is in the process of input and the interrupting program includes an 
INPUT statement or a KEYIN$ routine to get a reply. Since two partitions are assigned 
to the same terminal, keyboard input may be split between the two partitions. If an 
operator is performing fast numeric input and the CALL ENVIRON program's input is 
reached before the original program clears the keyboard buffer, data will be lost to 
the new partition. 


In the example above, the second CALL ENVIRON statement is necessary to return 
the partition to the original terminal. 
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C.1.3.2 Call Wizard Statements 


definition: CALL WIZARD statement 


CALL WIZARD (Numeric Expression[,String Array ]) 


A CALL WIZARD statement consists of the words CALL WIZARD followed by an open 
paren followed by a numeric expression, with a value of 0 or 1, optionally followed 
by a comma and string array, followed by a close paren. 


The CALL WIZARD statement is used to provide a 100 byte inter-task communications 
buffer to all partitions. 


Example 1. 


Obtain Buffer: DIM A$(1) 
CALL WIZARD (0,A$) 
Test string array length , 0= flag not obtained 
, 100= flag obtained 


NOTE: At this time the buffer may be examined or changed, if the flag was obtained. 


Upon initializing RUN or RUNB a 100 byte buffer is established in memory and is 
initialized to all blanks. The user must obtain the buffer before data in the buffer 
can be examined or changed. This is done by dimming a string array to the length 
of 1, to avoid unnecessary use of memory space. The CALL WIZARD statement is 
then used to assign this array name to the WIZARD buffer by using both a numeric 
expression, holding the value of 0, and the array name (see Example 1). If the buffer 
is not in use the user will obtain the buffer flag. To see if the user did obtain the 
flag, check the string size. If it equals the buffer size (100 bytes) you have obtained 
it. If the string size equals zero then the user has not obtained the flag. 


The flag function is not an exclusive access or locking control. Once it has been 
obtained and released, it may be used as any other string array would be used. If 
the users wish to use the WIZARD buffer as an exclusive access buffer, it must be 
understood that the buffer flag is to be respected when it cannot be obtained. This 
is referred to as FLAG use. NON-FLAG use is the option to reuse the buffer as a 
string array after assigning a name to the buffer. It should be understood that other 
users may access the buffer at the same time another user has it, resulting in lost 
or incorrect data. 
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Example 2. 
Release Buffer: CALL WIZARD (1) 


The RELEASE BUFFER use of CALL WIZARD (see Example 2) is used when the user 
is finished with the buffer flag. 


In the FLAG use of the WIZARD BUFFER, the RELEASE BUFFER is used when the 
partition has finished examining or changing the data within. 


In the NON-FLAG use, the RELEASE BUFFER is used after the user has assigned a 
name to the WIZARD BUFFER. The buffer is then available for other partitions to 
obtain. 


C.1.4 Multi-User File Use 


The F-85's file manager supports multiple access to sequential, random and ISAM files 
in a multi-user environment. Certain restrictions are necessary to preserve data 
integrity and avoid pathological cases peculiar to multiple access files. 


The simplest, and first, restriction is on the number of open files and the range of 
logical file numbers (LFN's). The number of simultaneously open files is determined 
by the F parameter in the partition file (see C.1.1 for a discussion of the partition 
control file), and this number is also the maximum allowed LFN. Thus, in a partition 
with this control file line: 


F=7 C=5 M=50 P=MANCHAIN T=1 
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the LFN's would range from 0 to 7. The number of open files possible at any one 
time is also 7. The printer does not count as an open file in this sense: LFN's 0 
through 7 could all be open at once, if desired and there was no contention from other 
partitions. 


The simplest ease, the system printer, may be open to only one user at a time for 
obvious reasons. An attempt to open the printer by another task after one partition 
has it open will result in an error status; OPEN (LFN=0) statements should therefore 
be trapped to give a printer busy message and return to the menu, or to spool the 
print file pending free time on the printer, or both. 


Sequential and random access files can be open by several users at once. Unlike ISAM 
files, however, these files are not subject to the exclusive access and record locking 
rules of ISAM, although random access records can be locked. Care must be used by 
the applications programs, therefore, not to delete a file another program is reading, 
and not to delete or modify a record another file is accessing. 


Sequential files are system buffered, so additional care should be used with this type 
of file. Exact synchronization of file data between tasks is not possible with this 
type of file. 


Reading random access files with MODE="R" and LOCK=1 (the default value) locks 
the record until another operation is performed on the file by the same user, as with 
ISAM files. However, unlike ISAM files, random access records need not be locked 
to be rewritten. 


ISAM files can be opened in either multiple access or exclusive access modes. Operations 
which change the external characteristics of the file require exclusive access with 
ISAM files. These operations include RENAME, DATE, CLOSE-delete and OPEN-clear- 
records (the latter grants exclusive access if it succeeds). An attempt to open an 
ISAM file in an exclusive access mode will fail (give an error status) if the file is 
already open in another partiton. 


In addition, ISAM records must be locked in order to rewrite or delete then. An ISAM 
record is locked by being read with the LOCK keyword set to 1 (the default value). 
Only one record per file per user can be locked; any subsequent operation on that file 
by that user unlocks the locked record, including another read. Locked records may 
not be accessed by other tasks, even though the file as a whole may be in use by 
several different tasks. In addition, an UNLOCK statement also unlocks the record 
(UNLOCK is only effective for records locked by the UNLOCK'ing program—one task 
cannot unlock the record another task locked). 


The exclusive access and record locking capabilities of ISAM are designed to prevent 
several pathological cases: deleting a file another user has open; renaming a file another 
user is using; changing or deleting a record another user is reading, changing or deleting; 
and so on. 


The "Deadly-- Embrace" 
Application Alpha needs files A, B and C to do a sort/write; Application Beta needs 


B, C and D to do a purge/sort/merge. Alpha gets exclusive access to A and B; Beta 
gets exclusive access to C and D. Neither will give up. 
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This is the "deadly embrace." It results in two dead programs, a pair of unhappy 
operators and users, and severe embarrassment to one or more applications programmers. 


One solution is a retry and release routine, to seek access several times, over a period 
of time determined by the program (and, preferably, by the operator as well), with 
release of files already accessed if the needed group of files are not all available 
within a set time. 


Another solution is a communications file available to the various applications, giving 
operators and programs a way of communicating their needs and adjudicating access. 


Another solution is to structure the group of concurrently running applications to avoid 
multiple exclusive access needs and to minimize the time any program has a record 
locked. 


There are many variations and combinations of these solutions. The proper solution 
will fit the design of the applications involved. This problem becomes particularly 
accute when several partitions are to run the same applications at the same time. 
Applications must be designed with a solution in mind. 


C.1.5 Planning Multi-User Applications 


Multi-user applications require program designers to consider a number of factors in 
addition to those considered for single-user environments. Overall design considerations 
include partition design and control, program space/segmentation planning, application 
program interaction planning, printer access and system utility usage requirements. 
Individual program design considerations include common area structure, wait time 
handling, error trapping, file access handing and file and program security. 


Every application in a multi-tasking environment must be designed to work efficiently 
with the other active applications. The work flow of the entire multi-tasking system 
must be analysed to meet peak demand period requirements and to effectively use 
off-hour time. In addition, the combinations of program segments which may be active 
in different partitions must be analysed to prevent conflicts among the concurrent 
applications, 


Partition Design 


Subsection C.1.1 discusses size requirement calculation and the other basics of partition 
design. Primary factors in designing a set of partitions are the number and type of 
separate tasks to be served at once in peak, normal and off-hour operations, the size 
of program segments versus speed requirements, and the frequency of partition configu- 
ration changes expected. 


In general the overall applications plan will determine the partitioning system. A 
group of tasks requiring extensive printer use, for instance, makes a special printout 
partition and program attractive, to allow each application to spool print files which 
the printout program will then access for on-going printing. A group of tasks requiring 
only sporadic printouts, on the other hand, would make callable print routines resident 
in the application partitions attractive. 
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As always, memory size versus speed is the primary tradeoff. Larger program segments 
and more manipulation of data in internal memory can minimize disk I/O and increase 
running speed, while disk-resident data and small program segments allow more simul- 
taneous tasks and more cost-effective use of the application's human and machine 
resources. In many cases the gain in speed by allowing larger program segments is 
not significant; in others, speed may be a critical factor and the time saved may be 
significant. 


In some applications, changing partitioning on a regular or a demand basis may be 
desirable. If a peak time requires extensive input, a space-eating data manipulation 
program which could be delayed to normal (or off-hour) operating times could be 
evicted and a set of peak-time partitions installed. If the application makes it 
attractive, a regularly scheduled shut-down and reconfiguration could be established, 
allowing a shift of input operators to work the morning, say, while executive query 
programs and report generation programs were installed at the lunch break. 


If frequent reconfiguration is planned, the applications should include a close-down 
routine which gives the console operator confirmation that all tasks are finished and 
data is preserved before shut-down and reconfiguration are performed. 


Program Space/Segmentation Planning 


Since partition size is a function of the largest program segment which will run in 
the partition, while minimizing disk I/O is a normal speed consideration, planning 
application's program segments properly is a key to efficient use of the multi-tasking 
F-85. 


The first step is to examine the normal flow of the task(s) to be accomplished in a 
partition. The application's system should be human-engineered to prompt the operator 
to perform tasks in the proper order and to train the operator to accept the speed 
constraints of the various sections of the application willingly. The operator should 
‘feel good about her/his machine, in other words, while performing in a way which 
allows the applications programs to operate efficiently. 


Once the tasking flow is established, the required segments of the program can be 
planned with an eye to the available space. Typically, the partitions required will be 
subject to one or more "givens", other applications programs, already written, requiring 
partitions of a given size. From the partitioning plan, the amount of space available 
to the applications is fixed and segments must be planned to fit that space. Since 
programs inevitably grow larger than originally planned, ideally the partitioning scheme 
would have a certain amount of flexibility. In fact, however, most partitioning schemes 
will tend to be Procrustean, so adherence to standards will normally need to be strict. 


Segmenting requires consideration of the flow of immediate tasks and the previous and 
subsequent tasks (outside the present segment). Use of the COMMON statement and 
the common area of memory allows free interchange of data among segments (and 
between the main routine of a segment and any external subroutines resident with it), 
but care must be taken to ensure both that the proper data is passed to subsequent 
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segments and that the passed data is in the expected form. Leaving out a vital but 
small subroutine when segmenting a large program may seem like a simple error to 
avoid, but it is also an easy error to commit. 


In the ideal case, each program segment will be a sensible subroutine of the total 
program, accomplishing a complete task (or subtask) and chaining in the next segment. 
An effective, structured organizing procedure is to write each segment as a set of 
relatively small subroutines. When a new segment is needed, the subroutines needed 
can be collected from the program's subroutine library, a few special purpose routines 
added, and the new segment given a segment (program file) name. In most cases, the 
name of the previous and subsequent segments should be maintained in the common 
area, to allow the same segment to be called by several other segments and to chain 
to the appropriate next segment when finished. 


If needed, a "program" and "program counter" could be maintained in the common 
area, each segment incrementing the counter as it chains in or out and the "program" 
determining which segment follows. Properly designed, this would allow creation of 
a "macroBASIC" applications language with "macros" consisting of applications segments. 
This macro language would have the advantage of minimizing program file space on 
the multi-tasking system disk, since all of the partitions would call the same set of 
segment files except for the initial, "macroprogram" file designed for the specific 
applications, which "programs" the partition. 


If segments cannot be complete, it is desirable (if at all possible) to avoid repeated 
back and forth chaining, with one part of an iterated task performed in one segment 
and another part in another segment. In most cases, it is possible to perform all of 
one part (writing data to a scratch file if necessary) before chaining to the segment 
which completes the iterated task. 


If a large number of segment pairs or segment groups required back-and-forth chaining 
and this slows execution below allowable limits, this is a sign that either the partition 
is too small or the program tasks have not been properly defined for multi-tasking 
implementation. 


Application Program Interaction Planning 


Multi-tasking applications typically will need to share access to one or more files and 
may share time on the system printer as well. In addition, one or more terminals 
may need a way to communicate to the console operator, particularly if the partitioning 
is regularly or frequently reconfigured. 


File access considerations are discussed briefly in Subsection C.1.3. The three main 
solutions to access conflicts are retry/release routines, which will not hold exclusive 
access or record locks beyond a limited time; file/record adjudication routines, which 
allow two or more applications to decide which needs access most and grants it; and 
conflict minimalization structures, which avoid access conflicts in the inherent design 
of the group of applications (as, by not allowing more than one routine needing exclusive 
access to be called by the various partitions). 
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To allow communication among terminals or to give a program status report to the 
console, a mailbox file should be established. Either a random or an ISAM file can 
be used; in either case, at least one control record should be present. One scheme 
is to use an ISAM file with records 0, 1, 2 and so on being the message control record 
for its corresponding terminal. When a message record is written, its key is inserted 
in the appropriate message control record. The message control record is accessed 
from the main program, or on some other regular basis, by each partition. After the 
message(s) are read, the message control record is cleared. 


For program status reports, a simple scheme is to use a random access file with 
records 1, 2 and so on giving the current status of the corresponding partitions. Each 
partition would write its status in its record, while the console would read it as desired. 


Printer Access, System Utility Usage Requirements 


Some applications need extensive use of the printer in all partitions, while others need 
printer output only on an infrequent basis—for monthly reports, say. Likewise, in an 
environment where program development and debugging is desired in addition to business 
applications, provision for system utility use must be made, while pure business 
applications will not need the system utilities. 


The printer and the system utilities are special cases of exclusive use. For obvious 
reasons, no more than one program can access the printer at one time. Likewise, 
because the system utilities like COMPILE require single-user mode, they also require 
exclusive access—a more stringent case than the printer, since other tasks can continue 
while one program uses the printer, while use of the compiler forces all other tasks 
off the F-85. 


There are several solutions to the printer's requirements. One option is to reserve 
one partition for a printer program which accesses a printer control file and a series 
of spool files generated by the other active programs. One option is to simply trap 
all OPEN (LFN=0) statements to give a printer busy message and return to the menu 
for other operations until the printer comes free. This option can be elaborated by 
a communications file giving the operator notice that the printer has come open. 
Another option is to trap OPEN (LFN=0) statements to spool print files when the 
printer is busy, with a later message reminding the operator to print the spool file. 
Another option is to spool all print files and to run a batch-mode print operation in 
off hours. 


When spooling print files, the printer control functions of STAR BASIC are converted 
automatically to the appropriate control codes, upon output (see Table 2-14, 
Video/Printer Control Function Sizing). However, the CARR=n option in the WRITE 
statement control list is not available in spooling, so output which may be spooled 
must not use CARR=n. 


UO 
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A simple spooling switch would look like this: 


N$="" 
N3=0 
U=0 
OpPrtr: OPEN (LFN=U,ERL=PrinterBusy,FILE=N$,OPT=N3) 


REM other code here 


WRITE (LFN=U) PrintLine$ 


‘ REM other code here 


PrinterBusy: U=7 
N3=1 
counter=counter+1 
N$="spool"&counter 
GOTO OpPrtr 


In environments where system utility use is required, it will have to be restricted to 
times when the other applications can be shut down. Debugging is possible within a 
partition without interfering with other programs, but only on a very limited basis 
(running the program and using the RUN debug commands). 


Individual Program Design Considerations 


Common area structure: Proper use and structuring of the common area of memory 
lets program segments chain in and out without requiring disk access to preserve data 
from one segment to the next. In addition, data held in the common area is available 
to the main routine and all external subroutines in a segment. The data in the common 
area is assigned to variables through the COMMON statement. This allows the program 
to distribute the data in a variety of ways, appropriate to the given segment. If a 
single string holds the common data in one segment, for instance, that string could 
be divided among three—or 63—string variables and arrays in another segment. 


Care must be used with the common data, however. Numeric and string data must 
not be confused and the appropriate data in the correct form must be in place for 
the next segment when a segment chains out. Proper structure in the common area 
will make program debug and maintenance simple; improper design can create intense 
problems for sloppy programmers. 


Wait time handling: Program segments requiring access to the printer, exclusive access 
to files, or access to potentially locked records or files open in exclusive access to 


other partition's programs must include a provision for controling wait times. The 
operator should normally be given the option of waiting for a condition to clear, 
preferably for an amount of time fixed by the operator, or to return to the menu for 
another task. 


Error trapping: RUN automatically returns to the main program upon carriage return 
input to the asterisk * prompt after an abnormal termination, but this should not 
normally be used in business applications except as a last resort. I/O errors should 
normally be trapped such that file conditions are set to a safe state, an appropriate 
message is given to the operator and the normal return to the appropriate menu is 
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made. Naturally, error traps must also ensure that catastrophes (hardware faults, and 
so on) are detected and execution does not continue in the event of a catastrophic 
error. 


File access handling: As discussed above, there are a variety of strategies aimed at 
giving the appropriate program access to files in the event of conflicts. Each segment 
in applications programs must be structured to ensure that the conflict avoidance 
strategy is implemented properly. 


File and program security: Since the keylock option on the F-85 may not be enough 
in some multi-tasking applications to guard sensitive files (if, for instance, a supervisor- 
level operator is using the payroll program while other partitions are active), programs 
must include file security procedures more stringent than those required in a single-user 
environment. A password system is the most commonly used security measure, with 
the password changing on a frequent basis. Concatenating the proper operator's Social 
Security number with the day of the month is a simple svstem—there are obviously 
an infinite variety of possibilities. 


Care should be taken in establishing the password system, however, to establish a 
proper guard but also allow for potential disability of the key operator or the all too 
common case of the key operator's forgetting the password. 


C.2 SIMILARITIES AND DIFFERENCES 


STAR BASIC is an enhanced, extended language which includes D-BASIC (with some 
exceptions) as a subset. STAR BASIC and its accompanying system and utilities supports 
multitasking, greatly enhances the flexibility and strength of the original language and 
provides significant gains in performance. STAR BASIC enhancements aid in structuring, 
coding, documenting and maintaining complex applications packages. In addition, 
improvement in both compilation and execution times aid both program development 
and application throughput. 


In larger configurations, the multitasking interpreter supports up to five separate STAR 
BASIC programs running concurrently, with up to four additional video display terminals 
added to the F-85 through the multiport communications interface. 


Where syntax differs between STAR BASIC and D-BASIC, in most cases the conversion 
can be made by using the CONVERT utility (refer to Star Basie Utilities Reference 
manual). Where direct machine translation may differ from the original intent of the 
D-BASIC program, CONVERT flags the statement to let the programmer analyse usage 
and insure equivalent operation. 


Because D-BASIC and STAR BASIC use somewhat different file formats, D-BASIC data 
files will need to be converted to STAR BASIC through the use of the FILECON file 
conversion utility (refer to Star Basie Utilities Reference manual). FILECON is designed 
to be used with the BATCH utility (see Subsection 1.7) as needed, allowing unattended 
conversion of large files and of groups of files. 


The similarities and differences between D-BASIC and STAR BASIC are summarized 
in Table C-1. 
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Table C-1, Release 1 and 2 Similarities and Differences 


D-BASIC STAR BASIC 


Compiler, run-time invocation 


requires 5 commands: requires 3 commands: 
call compiler compile 
compile run 
quit compiler object name (load-and-go) 


call run-time 
name object file 


Diskette storage during compilation 


required for object code only seratch space on disk required as well 
Integers 

integers in range 0-32767 no integers, all numerics are floating 

integer arithmetic supported ere arithmetic 

(5/2=2; 32767+2=-32767) (5/2=2.5; 32767+2=32769) 


Transcendental functions 


intrinsic functions include: transcendental intrinsic functions are 
EXP(x) exponential of x included as function subroutines, 
SGN(x) sign of x viz.: 


LOG(x) natural logarithm of x 
ABS(x) absolute value of x 


RND(x) random number range 0 to 1 FUN ABS(x) 

SQR(x) square root of x IF x LT 0 THEN EXIT -x 
EXIT x 
END 


Function-definition statements 


defined in-line in single-line defined in external subroutine; more 
DEF statement; general form allows creation of both 
numeric user-defined functions only utility and I/O functions; both string and 


numerie functions definable 
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Table C-1, Release 1 and 2 Similarities and Differences 


D-BASIC 


STAR BASIC 


String Arithmetic 


conversion functions are available; 
conversion functions must be used to 
convert string-to-numeric and 
numeric-to-string 


conversion functions are available; 
mathematical operators also convert types 
(i.e., A*D+36&F$ is a string expression; 
(D$&F$&R$)+T is a numeric expression) 


Array dimensioning 


numeric arrays single or double 
dimensioned 

string arrays single dimension only 
single character string arrays must 
be DIM'd 

A$(6,9) specifies sixth to ninth 
characters in A$ 


A$(6;9) not allowable syntax 
string arrays are variable in length 


value assignment only in LET 
statements or I/O statements 


numeric arrays single or double 

dimensioned 

string arrays single or double dimensioned 

single character string arrays need not be 
DIM'd 

A$(6,9) specifies sixth through final character 

in the ninth string of the two-dimensional 

array A$ 


A$(6;9) specifies 9 characters 
starting at the 6th character of A$ 


string arrays may be variable or FIXED 
(blank-padded on the right) in length 
memory locations can be shared; value 
assignments include BASE statement, as 
well as LET and I/O 


Statement length 


only a single statement per line; 
only a single line per statement 


only a single statement per line (exception: 
allows REM after other statements) 
statement may stretch over several lines 


Program chaining 


CHAIN A$,U 

invokes program A$ from unit U; 
clears memory, leaves files open; 
values passed only through files 


C-16 


CALL CHAIN(A$,U) 

invokes program A$ from unit U; 

clears memory, leaves files open; 

values may be passed through COMMON 
memory area 
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Table C-1, Release 1 and 2 Similarities and Differences 


D-BASIC STAR BASIC 


Statement labels, variable, array, subroutine and function names 


statement labels must be numeric statement labels can be numeric or 

: alphanumeric with up to 32 characters; 
variable and array names must be one variable and array names can be up to 
or two characters, the first alphabetic, 14 characters long, the first alphabetic, 
the second numeric only; the rest alphanumeric; 
subroutine names up to six alphanumeric subroutines names the same as numeric 
characters long, the first alphabetic; variable names, up to 14 characters long; 
function names are FN followed by a function names are the same as variable 
numeric variable name; names, up to 14 characters long; 


Subroutine definition and invocation 


CALL "Subname":A,B,C$ CALL Subname(A,B,C$) 
is external subroutine call form; is external subroutine call form; 
SUB "Subname":D,E,F$ SUB Subname(A,B,C$) 
is corresponding subroutine declaration; is corresponding subroutine declaration; 
SUB statement DIM's arrays explicitly: SUB statement DIM's arrays implicity: 
SUB "Name":A$(100) SUB Name(A$) 
DIM A$(1) 


if A$ were length 100 when passed, 
the DIM statement above would 
declare it an array and its length 
would be preserved; 


SUBEND statement ends all EXIT statement sends values back to 
external subroutines and passes values main routine (and may appear anywhere 
back to main routine; in subroutine); 
END statement ends subroutine (and all 
routines) 
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Table C-1, Release 1 and 2 Similarities and Differences 


D-BASIC 


STAR BASIC 


Error trapping, I/O and non-I/O errors 


ON ERROR GOTO statement label 
directs execution to statement if any 
execution-time errors occur; 


I/O errors trapped by ON ERROR; 


ERR returns all error numbers; 


no multitasking 


ON ERROR executable statement 

performs statement if error occu 3; however, 
I/O errors can be trapped by a control 
group within the I/O statement: such errors 
do not trigger ON ERROR trap; 

I/O errors may be trapped by within-the-I/O 
statement control group or by ON ERROR 
ERR returns all error numbers except I/O 
errors trapped by a within-the- 

statement I/O error trap; IOERR 

returns I/O error numbers only; 

errors in multitasking system cause return 
to option menu after error message 

and recovery effort; 


PRINTUSING, INPUTUSING: output and input editing 


PRINTUSING statement or 
INPUTUSING statement with image 
statement or internal image string 
formats and edits output and input 
data to determined forms 
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PRINT, WRITE and INPUT statements 
with EDIT$ functions and FORMAT control 
group format and edit output and input 

to determined form; EDIT$ may also be 
be used to edit data internally, in 
assignment or conditional statements; 
FORMAT group also allows control of disk 
storage formats, to save disk space; 
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Table C-1, Release 1 and 2 Similarities and Differences 


D-BASIC STAR BASIC 


LINPUT, INPUT operations 


LINPUT reads string input into a single INPUT statement accepts both numeric and 
string variable; INPUT accepts numeric _ string input with these rules: 


or string input, reading into a variable 1) all numeric variables on I/O list 
list which may be string, numeric or set to 0; all string variables set 
mixed; to null (or all blanks, if FIXED); 

2) each numeric variable obtains 1 


value from keyboard; any non- 
numeric character terminates 
numeric input; leading non- 
numeric input to numeric variable 
causes I/O error; 
3) string variables obtain characters 
from keyboard until string variable 
is filled to its declared length or a 
carriage return terminates input; 
NOCR,NOFILT,NOECHO controls allow KEYIN$ function accepts a single, no filtering 


no carriage return, no filtering, no no carriage-return, no echoing character 
echoing on video, input through LINPUT from the keyboard; function may be used 
statement anywhere a string variable is allowed; 


Video, printer control statements and functions 


PRINT and PRINTUSING statements PRINT statements output to video, 
output to video or printer; control WRITE statements output to printer 
groups in data allow print position or video or files; control functions in 
control, ete.; data allow print position control, etc.; 


control functions may be used anywhere 
string expressions are allowed; 
commas advance to intrinsic tabular commas separate items on output list, 
columns, semicolons separate items on print position is always determined by 
output list, both commas and semicolons control functions (commas do not cause 
suppress carriage return-linefeed at end a tab, and semicolons are not used); 
of line; carriage return-linefeed is suppressed 
by using control group CARR=0; 
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Table C-1, Release 1 and 2 Similarities and Differences WY 


D-BASIC STAR BASIC 


I/O statement control group syntax 


uses parameter-positional control uses keyword control group control list: 

list: various controls are sorted by each parameter is marked by its key word, 

order on list, which programmer viz.: 

must remember; viz.: 

OPEN pl,p2,p3,p4 OPEN(LFN=p1,FILE=p3,UNIT=p4) 

errors trapped by ON ERROR I/O errors may be trapped by internal ERL 

statement (error line) and EOF (end-of-file) control 
groups, or an ON ERROR statement may be 
used; 


APPENDIX C C.3 HIGH RESOLUTION MATRIX PRINTER 
OPERATING SYSTEMS SUPPORT 


C.3.1 INTRODUCTION 


This section is to aid the STAR BASIC user in some programming differences for the 
High Resolution printer (800XR) option. The Codes and sequences contained within 
this section apply only in conjunction with the High Resolution Printer. 


C.3.2 CRT SUPORT 


The operating system supports alternate font selection for the CRT. Selection of 
standard or alternate font pairs is immediate and maintains the current screen size. 
Change of screen size (large or small font with the STAR BASIC "CS$" function), 
occurs in the existing font pair. Support for the 32K CRT font ROMs is possible with 
the 800XR series; new functions for console driver calls is also provided by the STAR 
BASIC function "CRT.FONT$" in HRMP.LIB on the Utilities diskette. 


C.3.3 FONT SUPPORT 


STAR BASIC programs utilizing the printer may require the loading of additional fonts 
into the printer controller. The printer controller will accept up to 5 different fonts. 
This makes a possible total of 7 different fonts simultaneously loaded if the two 
resident (always present) fonts are counted. The printer controller has 11,520 bytes 
of memory for storing font data. 


There are provisions to selectively add, delete or change which fonts are used by the 
printer. This flexibility allows the user many font styles within a document. Before 
loading fonts for the first time, the user should clear the character generator memory 
by issuing a "DELETE FONT N" command (refer to Table C-3) to clear all fonts, this 
should avoid memory overflows, errors, etc.. 


New font styles may be added to the printer by issuing an "FONT N" command where 
"N" is a user defined font designator number. Following this command, the corresponding 
font file must be loaded. Values of "N" must be between 3 and 7 inclusive. N=1 and 
N=2 are reserved for the resident 10 and 16.55 pitch data processing quality fonts 
respectively. The user may add a font to those already loaded. If the font designator 
number has previously been defined, that font will be deleted before the new font is 
loaded. 


Previously defined fonts may be deleted selectively by issuing a "DELETE FONT N" 
command where "N" is the previously defined font designator. This will result in the 
removal of the respective character generator and font entry from the printer. Delete 
font "0" will result in clearing all fonts. Before deleting a font the printer will print 
all bufffered lines to avoid deletion of a font needed to print those lines. 


The operator may switch to any font previously loaded by issuing a "SELECT FONT 


N" command. "N" designates the desired font. All requests to switch font which has 
no corresponding data will result in an error. 
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C.3.4 CHARACTER SET AND CONTROL CODES 


Listed on Table C-2, are the codes recognized by the printer controller. Note that 
the codes are interpreted differently if they are part of an escape sequence. 


Code (hex) Dec. 


00 0 


01 to 07 i=7 


08 8 


09 9 


0A 10 


0B 11 


0c 12 


0D 13 


OE to 11 14-17 


12 18 


ASCI Name 


NULL 


BS 


LF 


FF 


CR 


DC2 


Table C-2, Printer Control Codes 


Printer Action 


NULL - Terminates the line and flushes 
all accumulated line feeds. 


Terminates the line. 


BACKSPACE - Terminates the line and 
moves virtual carriage one spacewidth, in 
the last font selected, to the left. 


Terminates the line. 


LINE FEED - Terminates the line and 
causes one line feed to be accumulated. 


Terminates the line. 


FORM FEED - Terminates the line, flushes 
all accumulated line feeds and positions 
paper ready for line one on the following 
form. 


CARRIAGE RETURN - Terminates the 
line and positions the virtual carriage at 
eolumn 1. 


Terminates the line. 


TOGGLE UNDERLINE - This code is 
entered into the line buffer. It turns on 
underline if underline is off and turns it 
off if it is on. Once underline is turned 
on, it remains active until another DC2 
is encountered or until the line is 
terminated. Underlining somewhere in the 
line forees half speed printing. 
Underlining is done in the last pass of the 
line at the pass height of the last pass 
using wire 9. Underlined spaces and unit 
separators are considered to be printables. 
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OPERATING SYSTEMS SUPPORT 


Table C-2, Printer Control Codes (cont.) 


Code (hex) Dec. ASCII Name 


13 to 1A 19-26 


1B 27 ESC 
1C to 1F 28-31 
20 32 SP 


21 to HIGH 33-239 
FILTER 


HIGH FILTER + 1 to EF 
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Printer 


Terminates the line. 
ESCAPE Start of an escape sequence. 


Terminates the line. 


Space character. 


PRINTABLE CHARACTERS - These codes 
are entered into the line buffer and when 
the line is terminated, they are printed 
according to the characters generator for 
the font. 


Ignored by the printer. 
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U 
C.3.5 HIGH RESOLUTION MATRIX PRINTER ESCAPE SEQUENCES 
Escape sequences are completed without interruption by keyboard entry of printer 
control codes or depression of the STOP key. The Escape sequences recognized by 
the HRMP and their respective definitions are listed in Table C-3, and the text following 
the table. When used, "N" is an eight bit number. Memnonics used are ASCII 
abbreviations. LSB stands for least significant byte and is an eight bit number. MSB 
stands for most significant byte and "N" is an integer. 
Table C-3, HRMP Escape Sequences Quick Reference Chart 
SEQUENCE ASCII HEX DEC FUNCTION 
NUL 00H 00 
ESC + SOH + BYTE *T SOH 01H 01 SET FORM LENGTH 
STX 02H 02 
ESC + ETX *T ETX 03H 03 SET LARGE FONT 
ESC + EOT *T EOT 04H 04 SET SMALL FONT 
ESC + ENQ T ENQ 05H 05 PRINT CODE REV LEVEL 
ESC + ACK + LSB + MSB T ACK 06H 06 FINE SET FORM LENGTH 
BEL 07H 07 
BS 08H 08 
ESC + HT + BYTE * HT 09H 09 HORIZONTAL TAB 
ESC + LF + BYTE *T LF 0AH 10 SET LINE SPACING 
ESC + VT + BYTE *T VT 0BH 11 VERTICAL TAB 
ESC + FF *T FF 0CH 12 SET TOP OF FORM 
ESC + CR + LSB + MSB CR 0DH 13 SET LEFT MARGIN 
ESC + SO + LSB + MSB TSO | 0EH 14 FINE HORIZONTAL TAB 
ESC + SI + BYTE T SI OFH 15 FINE SET LINE SPACING 
ESC + DLE + LSB + MSB T DLE 10H 16 FINE VERTICAL TAB 
ESC + DC4 + LSB + MSB T DC4 14H 20 MOVE CARRIAGE 
NAK 15H 21 
ESC + SYN + ADR + LSB SYN 16H 22 MEMORY TEST 
ADR + MSB + BYTE 
ESC + ETB ETB 17H 23 STOP LOADING FONT 
ESC + CAN +N T CAN 18H 24 DELETE FONT N (0=ALL) 
EM 19H 25 
ESC + SUB +N SUB 1AH 26 SELECT FONT N 
ESC 1BH 27 
ESC + FS +N T FS 1CH 28 START LOADING FONT N 
ESC + GS~ + (32 BYTES) GS 1DH 29 BURST FOLLOWS 
RS 1EH 30 . 
ESC + US +N US 1FH 31 VARIABLE WIDTH SPACES 
* = present in standard printer 7, | 
T = terminates line 


C-24 : REV. E 


C.3 HRMP APPENDIX C 


C.3.5.1 Set Form Length (ESC + SOH + N) 


This sequence will terminate the line and the sets the form length to "N' steps. Each 
step is 1/48th of an inch. Limits for N: 0<N< 240 


C.2.82 Set Large Font (ESC + ETX) 


This sequence will terminate the line and then select the 10 pitch resident data 
processing font. 


C.3.5.3 Set Small Font (ESC + EOT) 


This sequence will terminate the line and then select the 16.55 pitch resident data 
processing font. 


C354 Print Firmware Revision Level (ESC + ENQ) 


This sequence will terminate the line, flush all accumulated line feeds and then print 
the revision level of the EPROM's in the printer controller in the current font. 


C355 Fine Set Form Length (ESC + ACK + LSB + MSB) 


This sequence will terminate the line and then set the form length to (MSB * 256 + 
LSB) steps, where each step is 1/144th of an inch. Absolute limits: 0<¢= (MSB * 256 
+ LSB)<8192. , 


C.3.5.6 Horizontal Tab (ESC + HT + N) 


The execution of this sequence will cause the virtual carriage to move to column "N". 
Valid limits for "N" must be consistent with the character pitch used. For example, 
"N" must be less than 133 for 10 pitch and less than 219 for 16.55 pitch characters. 
While the printer is in proportional space font, horizontal tabs will be calculated based 
upon the width of the character with code 20H (normally the space character). Escape 
sequences having values of "N" greater than the maximum allowed for the font type, 
or N = 0, will result in an error. Absolute limits for N: 0<N < 240. 


C.3.5.7 Set Line Spacing (ESC + LF + N) 


This sequence will terminate the line and then set the line spacing to N/48 inch. "N" 
will be interpreted as an 8 bit value where bit 7 denotes the line feed direction. Thus 
a value of "N" of 127 will set the line spacing to +127/48 inch, while "N" = 130 will 
set the line spacing to -2/48 inch. 


C.3.5.8 Vertical Tab (ESC + VT + N) 
The execution of this sequence will result in virtual paper motion to line "N", "N" 
must be greater than 0 and less than or equal to the maximum line number defined. 


Vertical tabs to row 0 will result in an error. Tabs beyond the last line on the page 
will result in a form feed and an error. Absolute limits for N: 0€N <240. 
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C.3.5.9 Set Top Of Form (ESC + FF) 


This sequence terminates the line and then sets the internal step counter to one, 
thereby establishing the first line on the page. 


C.3.5.10 Set Left Margin (ESC + CR + LSB + MSB) 


This sequence is used to set the left print margin at (MSB * 256 + LSB) /480 + current 
left margin) inches from the left stop. This setting will then remain in effect until 
reset by another left margin sequence. The left margin can never be set to the left 
of the default margins: 0.57 inches from the left physical stop to the first printable 
dot in spur drive mode; and 1.77 inches from the left physical stop to the first printable 
dot in the friction feed mode. The left margin can be sent past the right side of the 
paper, no error is given and all further printing is suppressed. Note that the tabbing 
range will decrease when the left margin is moved to the right. 


©.3.5.11 Fine Horizontal Tab (ESC + SO + LSB + MSB) 


This sequence terminates the line and then moves the virtual carriage to (MSB * 256 
+ LSB)/480 inches from the current left margin. Limits are: 0<(MSB * 256 + LSB) 
+ (left margin in inches) * 480 <6608. 


C.3.5.12 Fine Set Line Spacing (ESC + SI + N) 


This sequence will terminate the line, flush all accumulated line feeds and then set 
the line spacing to N/144 inch. "N" will be interpreted as an eight bit value, where 
bit 7 denotes the direction. Bit 7 = "1" is the negative direction. Bit 0 to 6 indicates 
ee ae of 1/144th inch increments for every line feed. Limits for N: 0 

= N < 256. 


C.3.5.13 Fine Vertical Tab (ESC + DLE + LSB + MSB) 

This sequence will terminate the line and then set the internal step count to MSB * 
256 + LSB. Each step represents a vertical distance of 1/144th inch. Limits are: 0 
(MSB * 256 + LSB) form length in steps. 

C.3.5.14 Move Carriage (ESC + DC4 + LSB + MSB) 

This sequence terminates the line and then moves the carriage to a position (MSB * 
256 + LSB) /480 inches from the physical left stop in the printer. An illegal count 
will result in an error. Absolute limits: 0 <(MSB * 256 + LSB) < 6608. 

C.3.5.15 Stop Loading Font (ESC + ETB) 

This sequence should follow a font loading. When this sequence is received the font 
will be put in the internal font directory if there were no errors during loading. A 


font will be regarded as undefined by the printer until properly terminated with this 
sequence. 
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C.3.5.16 Delete Font (ESC + CAN + N) 


This sequence will terminate the line and then delete font "N" from the internal font 
directory. It will also compress the memory area used for fonts so as to leave room 
for more fonts. Note: "N" = 0 will delete all fonts; fonts 1 and 2 are resident fonts 
and cannot be deleted or replaced. Absolute limits for N: 3 <N{€ 7. 


C.3.5.17 Select Font (ESC + SUB + N) 


This sequence will select font "N". It can be sent at any time, even within a line or 
a word. It will cause the printer to use font "N" until another font is selected. 
Selection of a undefined font will result in an error. Also note, that N = 1 and N = 
2 will select the ROM resident 10 pitch and 16.55 pitch fonts without terminating the 
line as opposed to ESC + ETX and ESC + EOT. Absolute limits for N: 0<N ¢ 8. 


C.3.5.18 Start Loading Font (ESC + FS + N) 


This sequence will terminate the line, delete any font with designator "N", and then 
set up the printer to accept bursts of character generator data. Other codes may be 
sent in between bursts, although this is not recommended. Note that fonts 1 and 2 
are resident fonts and cannot be replaced. Absolute limits for N: 3<N<€7. 


C.3.5.19 Burst Follows (ESC + GS + (32 BYTES)) 


The (ESC + GS) prefix tells the printer that a burst of 32 bytes of character generator 
data is to be sent. If a memory overflow occurs while receiving a burst, an error 
will be sent after accepting the complete burst. Any data within the burst but after 
the overflow will be lost. Bursts may not be interrupted with other codes. 


C.3.5.20 Variable Width Space (ESC + US + N) 


This sequence will add a variable width space of width N/480 inch after the previous 
character. A maximum of 226 unit separator escape sequences can be sent within 
one line or an overflow will occur. Every time this sequence is sent, one line buffer 
location will be used. A unit separator of 0 will be ignored by the printer, and no 
entry into the line buffer will be made. Absolute limits for N: 0 (N < 256. 


C.3.5.21 Memory Test (ESC + SYN + LSB + MSB + BYTE) 


This sequence will write BYTE to memory location (MSB * 256 + LSB) in the printer 
controller and then read it back and compare. An error will be returned in the event 
of a miscompare. This sequence should be used in conjunction with the "F8" code to 
assure synchronization. Limits are: 16,383 <(MSB * 256 + LSB) < 32,768 and 0 < = 
BYTE 256. 


C.3.6 Other Support 


When the STOP key is in the up position, a CODE-1 is sent from the keyboard as an 
F-Code instead of the form feed/null sequence normally sent. 


CAUTION: A CODE-3 causes an automatic reset to 10-pitch draft font, this is 
equivalent to a "CS$(1)" funetion in STAR BASIC. The CODE-3 is used to print the 
sereen display. 
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APPENDIX D 
D.1 COMPILER ERROR MESSAGES 


Errors at compilation time abort the production of the object code file. Errors in the 
call of the STAR BASIC compiler generate messages on the video display; errors in 
the syntax of the source program appear on the printer, within the source listing if 
the N, L or P options are not chosen, on a separate page if the source listing is 
suppressed. 


Whether on the video display or the printer, STAR BASIC error messages appear in 
the following format: 


Error errornumber - message 


errornumber = a specific number assigned to each error message 
message = a brief text explaining the error which has been 


detected, which may be accompanied by an indication 
of the location of the error, such as a variable name 
or the column number within the line containing the 
error; messages are listed in Tables D-1 and D-2, 
below. 


Table D-1, Video Display Compiler Error Messages 


Error 

Message Meaning 

No input file An input filename was not specified in the COMPILE 
invocation 

Illegal option One of the options specified was not a P, S, X, E, K, 

N, L or C 

Control statement error The format of the invocation is in error 

xx error on input open 

xx error in printer 

xx error on allocate 

xx error on read The STAR BASIC compiler has received an unexpected 

= error on write status number xx from DX-85M; compilation terminated 

Out of memory’ No more memory was available to the compiler to 


complete compilation of the source program. 


Unsatisfied external or Program made of subroutines and functions with no 
no main program main line, or function reference and functions are not 
contained in the source. 
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Table D-2, Printer Compiler Error Messages 


Error 
Message 


Meaning 


Illegal character in col. xx 
No closing quote in xx 


Bad numeric field - xx 


Syntax - xx 


Subscript 


Subscript range - xx 


Statement format xx 


Z 
° 


label - xx 


xx not FIXED 


not BASED 


[33 


Expression syntax - xx 


Substring - xx 


Type mismatch 


Index 


A character not in the STAR BASIC character set 
was found in column number xx in the source line 


A string constant is missing a closing " number xx 
indicates the constant up to the error 


An element begins with a number but does not conform 
to the conventions of a numeric constant; xx represents 
the element up to the point of error 


Statement does not conform to the rules of formation 
for its apparent statement type; xx represents the 
element in error, if available 

Invalid subscript entry 


Subscript xx in a DIM statement is not in the range 
1 to 32767 inclusive; value of 1 assumed by compiler 


The general syntax of the statement is correct, but 
the element xx is illegal in this particular context, 
as in DIM A$(I1) FIXED FIXED 

Statement label xx has been specified (in a transfer 
statement, for instance) but not used to label a 
statement in the source program 

String arrays in COMMON statements must be fixed 


The source line attempts to BASE variable xx, but xx 
has not been declared BASED in a DIM statement 


The syntax of a string or numeric expression is in 
error; xx is the element in error 


The substring expression for array xx is in error 
The operands of a conditional expression are of 
different types; while mathematical operators perform 
type conversions, relational operators do not 


The index variable in a FOR or NEXT statement does 
not conform to the rules for index variables 
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Table D-2, Printer Compiler Error Messages (Cont'd) 


Error 

Message Meaning 

No "FOR" A NEXT has been encountered, but no matching FOR 
statement preceded it 

No "IF" An ELSE or ENDIF statement has been encountered 
but no matching IF statement preceded it 

Control list The I/O control list in the source statement is in error 

Unsatisfied external - xx A subroutine or function xx was invoked but is not 
de fined 

No main program Program made of subroutines and functions with no 
main line. 

Internal error A compiler system error has occurred; submit Software 
Problem Report to Durango Systems Ine. with source 
program 

( "END" missing The source file has been exhausted but no final END 
statement was found 

xx not a DATA statement The target of a RESTORE statement, statement label 
xx, is not a DATA statement 

Missing NEXT or ENDIF A FOR statement or an IF statement with no matching 
NEXT. or ENDIF statement was found 

Dup definition A variable, array, subroutine or function name is being 
defined for the second time (in DIM, SUB or FUN 
statement) 

xx already defined Statement label xx has already been used once 

Common list overflow - xx Too many variables used in a COMMON statement; 
xx is the element which was to have been added to 
the compiler list 

Table overflow - xx One of the compiler tables has overflowed: the 
program is too large in some respect (i.e., too many 
labels were used, or the number or total size of the 
variables are too large); xx is the element which was 
to have been added to the table. 


D.1 Compiler Error Messages 
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Table D-2, Printer Compiler Error Messages (Cont'd) 


Error 
Message 


Stack overflow 


Not an IOLIST 
Missing expression 
Stack underflow 


Bad name 
Book xx not found 


COPY within COPY illegal 


No library file 


Meaning 


An expression is too complex or too many GOSUBs 
or IF-THEN-ELSE-ENDIF or FOR-NEXT nests have 
been used for the compiler stack to hold entries for 
evaluation 


Label specified by IOLIST control group is not an 
IOLIST statement 


I/O control list faulty or variable/expression list is 
missing 


System error; submit Software Problem Report to 
Durango Systems, Ine. 


Function or subroutine name used illegally 
The named book does not appear in the library 


A COPY statement appears in the book currently being 
copied - this is not permitted. 


The compiler invokation does not include a LIB= 
specification, so COPY processing cannot be 
performed. 
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Error Meaning 
Code 
*0 No error. 


1-3 System Errors 

*] DX-85M system error. 

*2 I/O statement parameter value in error (check keyword groups). 
*3 Function not in system (ISAM call with no ISAM in DX-85M). 


4-10 Disk Errors 


*4 Disk media error. 

*5 Disk directory error. 

6 Disk directory full. 

7 Duplicate filename. 

8 Insufficient file space on disk. 
9 File not found. 

10 Disk unit unavailable 


11-25 File Errors 


Ce) 11 LFN already in use (you have that LFN open) or out of range (check 
system configuration). 
12 File already open (either by you or by another user). 
13 Sequential files only: insufficient file buffer space. 
14 Attempt to write/rewrite delete record in write protected ISAM File, or 


attempt to close delete/rename/date an ISAM File, write protected or not 
open exclusive access. Attempt to open a write protected File for write 
operations. Attempt to write to write protected File, or File open for read 


only. 
15 Open option wrong for record format. 
16 End-of-file encountered. 
17 Random file buffer not large enough for record. 
18 Attempt to close (delete or truncate), date or rename write-protected file. 
19 Attempt to random read or write to variable record (type V), file. 
20 Attempt to read file not open for read or update. 
21 Attempt to write to file not open for write, extend or update. 
22 LFN not open. 
23 Record locked. 
24 Record not locked. 
25 (reserved for future use) 
co * ABSOLUTE reads and writes return these codes: see page D-7. 
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Error Meaning 

Code 
26-29 Loader Errors (CALL CHAIN only) 

**26 Load file block count error (disk error - check disk and file). 

027 Load file block type error (disk error - check disk and file). 

+*28 Load file checksum error (disk error - check disk and file). 

+29 Load attempted outside of loader bounds (disk error - check disk and file). 
30-35 ISAM Errors 

30 ISAM open attempted on non-ISAM fixed record length file. 

31 ISAM record not found (MODE = "R" attempt). 

32 Duplicate ISAM key on write-add (MODE = "S") attempt. 

33. Index overflow on ISAM write-add (MODE = "S") attempt. 

34 Wrong length ISAM data record (system used only). 

35 ISAM file integrity error (analyze file for bad index or data). 

36-60 (reserved for future use) 
50-54 High Resolution MATRIX Printer 

50 FONT ALLOCTION ERROR - all printer memory available for font generator 
storage has been filled. 

51 FONT SELECT ERROR - a font was selected for printing which does not 
have a generator loaded or font number for generator to be loaded is out 
of legal range. 

52 TAB/MOVE ERROR - a horizontal or vertical tab or move command 
destination is outside the page boundary. 

53 STACK/BUFFER OVERFLOW - more unit separator escape sequences have 
been specified than the unit separator stack can hold, or more printable 
characters and unit separators and start/stop underlines and font selections 
have been specified than the line buffer can hold, or the fonts selected to 
be printed on the line have more unique pass heights than can be stacked, 
(current limits are 226 unit separator sequences, 1840 printables etce., in line 
buffer, and 16 unique pass heights). 

54 BAD ESCAPE SEQUENCE/MEMORY ERROR - an unrecognized escape 
sequence has been sent to the printer or, for the HRMP diagnostic program, 
a selected memory location is faulty. 

61-63 I/O Statement Errors 
61 I/O call parameter error: keyword and value in I/O statement not legal 


with file organization or other keywords in control list or not permitted 
in current I/O statement type. 


** These errors are always fatal (cannot be trapped). 


o 
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oO 


Error Meaning 
Code 


62 Data error: data type error (attempt to read non-numeric data into numeric 
variable or to write numeric data from non-numeric variable) or format 
error (format conflicts with record data) or insufficient data for read I/O 
list given or write data exceeds maximum data record size. 

63 1/0 FORMAT error: FORMAT string in read or write statement specifies 
data of type not matching variable type in I/O list or FORMAT string 
construction faulty. 


64-99 (reserved for future use) 


100-199 Non-I/O Errors 


100 Subscript out of allowable range. 
101 (reserved for future use) 

* 102 Illegal operation encountered, compiler or hardware error. 
103. RETURN attempted with no preceding GOSUB. 

* 104 Faulty CALL or function invocation: parameter type in CALL or invocation 

does not match argument type in SUB or FUN statement. 
105 CODE and ESC keys depressed. 
106 Dynamie stack requirements exceed available memory. 
107 String expression in numeric context could not be converted. 
co 108 Numeric expression used in character context could not be converted. 

109 Attempt to internal READ past end of DATA list. 


110-199 (reserved for future use) 


200-255 Programmer-definable errors (through ERROR statement or optional System 
Support Modules (OSSM), via CALL MACH Statement). 


Form of error message: ERROR number AT location number 
number = error code 
location number = program location (see compiler listing) 


ABSOLUTE READ/WRITE Errors 


No error. 

Hard disk error (unrecoverable read/write error). 
Parameter error (illegal unit or block number). 
Disk is write-protected. 

Unrecoverable read error on a write-protected disk. 


oe 


* This error (102 and 104) is always fatal. 
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SYSTEM ERROR MESSAGES 


FILE NOT FOUND Specified file not found in $DIRECTORY on unit desig- 
nated. 

ILLEGAL COMMAND Command word or parameter(s) not valid. 

BIN FMT ERR Loader error (binary format error). Usually because 


STAR BASIC program is submitted to : as if it were 
a machine language program. 
REPLACE DISK n Disk just removed from unit n contains open file(s). 
7 Reinsert diskette. WARNING: If same diskette is not 
reinserted, one or more files may be damaged. 

UNIT u(tp) NOT READY u(tp) unit is not transmitting a ready signal: insert 
diskette and close door. If disk unit does not exist in 
current configuration, CODE LOAD. 

u; is the logical unit number; 

t; is the CONFIG.SYS type descriptor character; 

p; is the physical disk address. 

NOTE: The "tp" pair will not necessarily match the 
CONFIG.SYS entry, since complex descriptors can be 
used for non-floppy disks. EX. If the disk described 
by "LL4=F1" were not ready, the message would read 
"UNIT 4 (FO) NOT READY". The physical device 
address is the IEEE "talk" address set in the controller 
switches and that would be 0; the fact it specifies the 
second directory is not relevant. 


DISK ERR Loader error with a media or disk unit basis. 

PRT JAM Printer jammed: clear jam, press CODE TAB to resume 
printing. 

PAPER OUT Printer has run out of paper: add paper, CODE TAB 
to resume. 

COVER/RIBBON Printer cover open or end of ribbon for mylar ribbon 
cartridge. 
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SYSTEM ERROR MESSAGES (cont'd) 


AUTOSTART OPEN ERROR Error in attempting to open $AUTOSTART file. 
AUTOSTART READ ERROR _ Error in attempting to read $AUTOSTART file. 


BKP ALREADY SET System breakpoint has already been set. 
BKP TBL FULL Breakpoint table is full. 
RST 1 EXEC Restart interrupt has been triggered by a CODE 


RESTART or a program fault (usually an attempt to 
run a utility from another system): CODE LOAD. 

TRAP n Trap interrupt has been triggered. See list of codes 
below. 


Trap codes are hexidecimal numbers. Only the high order (left hand) digit is significant; 
in addition, the seventh bit of the status word reflects the status of the optional key 
lock, giving two possible codes for each status. 


Ox or 8x CODE RESTART keys depressed: CODE LOAD to 
~ ~ restore system. 
1x or 9x Power fault. 
a 2x or Ax Bus timeout error. 

J 3x or Bx Power fault and bus timeout error. 
4x or Cx Parity error. 
5x or Dx Parity error and power fault. 
6x or Ex Parity error and bus timeout error. 
7x or Fx Parity error, power fault and bus timeout error. 


If a four digit hex code follows the trap message and code, the four digits represent 
the contents of the processor program counter. 
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$AUTOSTART The turnkey system control file. If an 
$AUTOSTART is present in the diskette directory 
at CODE LOAD, the system clock will be set 
through the input date routine from STARTU.SYS 
and the contents of the $AUTOSTART file will 
then be used as keyboard input (up to 40 characters 
are allowed). 


$DIRECTORY The diskette file which holds the organization of 
the diskette itself. $DIRECTORY is a fixed record 
length file with 64 byte records. Each file on the 
diskette is listed in a $DIRECTORY record. 


& Coneatenation, a binary mathematical operator. 
Coneatenation attaches the string value of the 
mathematical expression on its left to the string 
value of the mathematical expression on its right. 


i Multiplication, a binary mathematical operator. 
Multiplication adds the numeric value of the mathe- 
matical expression to its left the number of times 
equal to the mathematical expression to its right. 


+ Addition, a numeric mathematical operator. Addi- 

Cy tion combines the numeric value of the mathe- 
matical expression on its left with the numeric 

value of the mathematical expression on its right. 


- Subtraction, a numeric mathematical operator. 
Subtraction negates the numeric value of the math- 
ematical expression on its right and sums it with 
the numeric value of the mathematical expression 
on its left. 


/ Division, a binary mathematical operator. Division 
subtracts the numeric value of the mathematical 
expression on its right from the numeric value of 
the mathematical expression on its left succes- 
sively, returning the number of steps to zero. 


< Less than, a relational operator. Less than returns 
TRUE only if the value of the expression on its 
left is lower than the value of the expression on 
its right. String comparisons are by ASCII order. 
Less than does not perform type conversion and 
may only be used in conditional statements. 


Note: This glossary is in ASCII order. 
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<> >< 


ADDITION 


ALLOCATE 


ARRAY 


Less than or equal to, a relational operator. Less 
than or equal to returns TRUE only if the value 
of the expression on its left is less than or equal 
to the value of the expression on its right. String 
comparisons are by ASCII order. 


Not equal, a relational operator. Not equal returns 
TRUE only if the value of the mathematical expres- 
sion to its left is not identical to the value of the 
mathematical expression to its right. 


The assignment operator (used in LET statements), 
or equal to, a relational operator. The assignment 
operator sets the variable to the left equal to the 
expression to the right. The relational operator 
is TRUE if the expression values are identical. 


Greater than or equal to, a relational operator. 
Greater than or equal to returns TRUE only if the 
value of the expression to its left is greater than 
or equal to the value of the expression to its right. 
String comparisons are by ASCII order. 


Greater than, a relational operator. Greater than 
returns TRUE only if the value of the mathematical 
expression on its left is higher than the value of 
the mathematical expression on its right. String 
comparisons are by ASCII order. 


+, a numeric mathematical operator, performs addi- 
tion by combining the numeric values of the two 
mathematical expression on either side. 


To reserve disk space for a data file. ALLOCATE 
statements write the name and file information in 
the diskette directory, but do not write information 
in the file itself. 


The name for a set of values referenced by number. 
Arrays in STAR BASIC must be dimensioned in a 
DIM statement. They may be one or two- 
dimensional, BASED or FIXED. 


Note: This glossary is in ASCII order. 
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BASE STATEMENT A dynamic assignment statement. When an array 
is declared BASED in a DIM statement and the 
BASE is declared in a BASE statement, the value 
of the array is stored in the same memory area 
as the array on which it is based. 


BASED A declaraction in a DIM statement that the array 
will share memory with another array. 


BAUD Equivalent of bits per second. The baud rate is 
a measure of data transmission. The transmission 
rate of the F-85 must match the peripheral device's 
acceptance rate or data transmission errors will 
oecur. 


BDUMP The disk code display and print utility. BDUMP 
displays on the video or prints on the printer the 
code from designated blocks or files from the 
designated diskette. 


BUFFER An area of memory used for temporary storage. 
Buffers in STAR BASIC programs are variables or 
arrays. The operating system also uses buffers for 
various purposes. The keyboard buffer, for 
instance, holds up to 40 characters. Various file 
buffers are used as well—this usage is discussed in 
the CONFIG.SYS subsection. 


CALL The directive of the STAR BASIC statement which 
invokes external subroutines. CALL subname 
causes execution to pass to an external subroutine, 
just as GOSUB passes execution to an internal 
subroutine. 


CHAIN CALL CHAIN(name ,unit ) invokes a new program. 
All internal memory is cleared except for the 
COMMON memory area (if any), all files remain 
open, and the new object file is loaded and run. 
CHAIN is an intrinsic subroutine. 


CLOSE The directive of the STAR BASIC statement which 
ends active file use. CLOSE statements end the 
use of a file, releasing its logical file number (LFN) 
for re-use. CLOSE statements may optionally 
truncate the unused space from the end of a 
sequential file, or delete a file of any type. 


Note: This glossary is in ASCII order. 


Glossary 


COMMON 


COMPILE 


CONCATENATION 


CONDITIONAL EXPRESSION 


CONDITIONAL STATEMENT 


CONFIG.SYS 


APPENDIX E 


The directive of the STAR BASIC statement which 
declares one or more variables to use the COMMON 
area of memory; also, the name for the area of 
memory used. the COMMON area of memory is 
available to all routines active in a partition and 
is not cleared when a new program chains in. 
COMMON is used for inter-routine and inter- 
program communication. 


The compiler program. COMPILE takes source 
code and converts it to object code which can be 
run by RUN, the run-time monitor. 


&, a binary string operator. Coneatenation 
attaches the string value on its left to the string 
value on its right. 


A relational expression, or a conditional expression 
preceded by NOT, or two conditional expressions 
linked by AND or OR. Conditional expressions are 
used only in conditional statements. 


A logical test which determines action. A condi- 
tional expression is tested for truth and one or 
more statements are executed according to the 
results of that test. Conditional statements in 
STAR BASIC appear in both single and multi-line 
forms. 


The system configuration control file. 
CONFIG.SYS may be written with the EDIT utility 
or generated through the CONFIGURE utility. The 
parameters contained in the file determine the 
number of system buffers for files, whether the 
ISAM file manager will be present in the system, 
how many open fiels are allowed, and how the 
multicommunications ports (if any) are initialized, 
if CONFIG.SYS is present at CODE LOAD. 


Note: This glossary is in ASCII order. 
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C) CONSTANT A fixed value. "A" is a string (or character) 
constant, while 3.724 is a numeric constant. 


CONTINUATION SYMBOL The A. If used at the extreme left margin of a 
line, the continuation symbol marks the line as the 
continuation of the previous line. 


CONVERT The conversion utility, a STAR BASIC utility. 
CONVERT takes D-BASIC Release 1. source 
program files and converts them to STAR BASIC, 
flagging any special or questionable usage for 
manual inspection and/or conversion. 


COPY The file and diskette copy utility, a system utility. 
COPY duplicates files and groups of files, on the 
same diskette with name changes, or on another 
diskette, with or without name changes. 


DATA 1) A piece of information; 2) A statement holding 
one or more constants, used to supply data to a 
READ statement in internal I/O. 


DATE To change the date listing of a file's directory 
record. | 
co DELETE To eliminate a record from a file. | 
DIGIT One of the numeric characters 0123456789. 
DIM To dimension an array. When DIM'ed, arrays are 


declared to be arrays and their size and character- 
istics are specified. Arrays can be declared to be 
BASED (they will share memory with another array) 
or FIXED (in length). 


DIRECTIVE A "verb" in STAR BASIC. A directive is a reserved 
word used by the language processor to determine 
the statement type before evaluation. 


DIVISION /, a binary mathematical operator. Division sub- 
tracts the numeric value of the mathematical 
expression on its right from the numeric value of 
the mathematical expression to its left succes- 
sively, returning the number of steps to zero. 


DSCAN The disk scanning utility, a system utility. DSCAN 
reads each sector of the designated diskette, 
checking for hard disk errors. 


Note: This glossary is in ASCII order. 
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ERROR TRAP 


EXIT 


EXPRESSION 


EXPRESSION TYPE 
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1) To modify a text; 2) The system utility which 
allows creation and modification of source pro- 
grams. 


An intrinsic function which allows modification and 
formatting of data both in I/O and in internal 
manipulations. 


A STAR BASIC statement which can put a form 
feed between routines of a program without 


changing the title of the page. Operator oriented 
statement. 


A constant, variable, array or function. Elements 
are linked by the mathematical operators to form 
mathematical expressions. 


To halt both execution and compilation. 


Equal to, a relational operator. Equal to returns 
TRUE only if the value of the mathematical expres- 
sion on its left is identical to the value of the 
mathematical expression on its right. 


1) A mistake; 2) A statement which generates a 
specifie error, designated by the word which follows 
"ERROR" in the error statement. ERROR errors 
are always fatal errors. 


A set of lines designed to correct an error. Error 
traps are designated by ON ERROR statements 
and by the EOF and ERL keyword groups in I/O 


statements. 


To return from an external subroutine or function 
subroutine. Control passes to the line following 
the line which invoked the external subroutine. 
FUN EXIT's pass a value to the function name and 
evaluation of the statement containing the function 
name continues. 


An element, or an expression with a unary operator, 
or two expressions linked by a binary operator. 


Expressions are of two major types: mathematical 
(string or numeric) and conditional (relational or 
logical). 


Note: This glossary is in ASCII order. 
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Glossary 


EXTERNAL SUBROUTINE 


FATAL ERROR 


FILE 


FILES 


FIXED 


FORMAT 


FOR-NEXT 


FUN 


A subsidiary routine, headed by a SUB statement, 
designed to do a specific action. External sub- 
routines are isolated from the main routine except 
for values shared by either parameter passage or 
through the common area of memory (or through 
file data, of course). 


An error which causes a halt to execution. 


A eollection of organized information held on a 
diskette. Nine kinds are available on the F-85: 
Directory, Loading, System, Program, Object, 
Sequential data, Random Access data, ISAM data 
and ISAM index. 


The disk directory utility, a system utility. FILES 
displays the directory of the designated diskette 
and allows video or printed lists of specified file 
entries, name changes, file dating, and space 
measurement and display. 


Of fixed length. When a string array is declared 
FIXED in a DIM statement, its length is set at 
the specified maximum and blanks will be added 
on the right as necessary. However, the array will 
be filled with nulls until the first value is assigned. 
All two-dimensional string arrays are automatically 
FIXED. 


The diskette formatting utility, a system utility. 
FORMAT writes the sector headers and check 
diskettes for hard errors. FORMAT must be used 
on "factory fresh" diskettes before the F-85 can 
read or write them. 


To loop under the control of a numeric variable. 
The FOR statement (FOR I=1 to 256 STEP 4) 
identifies the variable and sets its range. The 
NEXT statement (NEXT I) causes a return to the 
FOR statement to increment and evaluate the value 
of I. 


A FUN statement heads every user-defined fune- 
tion. 


Note: This glossary is in ASCII order. 
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FUNCTION 


GE 


GOSUB 


GOTO 


GROUPING OPERATORS 


GT 


1/O 


IF-THEN 


IF -THEN-ELSE-ENDIF 


INPUT 


An array or variable name used to perform a 
predefined process. Instrinsic functions are part 
of STAR BASIC, while user-defined functions are 
written as external subroutines headed by a FUN 
statement. Functions are invoked by use in an 
expression. 


Greater or equals, a relational operator. Greater 
or equals returns TRUE only if the value of the 
expression to its left is greater than or equal to 
the value of the expression on its right. String 
comparisons are by ASCII order. 


To transfer to a specified location with the pos- 
sibility of return. A GOSUB is identical to a 
GOTO except that control will resume at the line 
following the GOSUB if a RETURN is encountered. 


To transfer program execution to a specified line, 
as in "GOTO P3", where P3 is a line label. 


The parens (). The grouping operators separate 
expressions into subgroups and designate the order 
in which the other operators will act. 


Greater than, a relational operator. Greater than 
returns TRUE only if the value of the expression 
on its left is higher than the value of the expression 
on its right. For string values, higher is judged 
by ASCII order. 


Input/Output. 


A test to determine subsequent action. An IF- 
THEN statement (IF condition THEN executable 
statement) executes the statement only if the con- 
dition is true. 


A conditional test to determine subsequent action, 
with the action lines stretching over several lines. 
If the conditional in the initial line is true, the 
lines immediately following it will be executed; 
ELSE lines execute if it is false. 


To put information into the F-85. INPUT state- 
ments take data from the keyboard, but input can 
also come from a_ disk file. See also, 
INPUT/OUTPUT (I/O). 


Note: This glossary is in ASCII order. 
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INPUT/OUTPUT 


INTERNAL SUBROUTINE 


IOLIST 


ISAM 


ISAM.SYS 


KEY 


LE 


LET 


LFN 


Glossary 


Taking data in or sending data out. Disk I/O is 
communication between the central processor and 
a diskette; printer I/O is communication with the 
printer; and so on. 


A section of a larger routine designed to perform 
a specific task. Internal subroutines are usually 
accessed by GOSUB and end with a RETURN, but 
other forms are also used. 


The directive of the STAR BASIC statement which 
supplies a variable list to READ statements and/or 
an expression list to WRITE statements. 


Indexed Sequential Access Method. ISAM files 
consist of two files: a master data file and an 
index (or key) file. The records of the master file 
are accessed by the keys in the index, which are 
kept in ASCII order. This type of file is extremely 
useful for data which is frequently used in sorted 
order. 


The ISAM file manager file. ISAM.SYS is loaded 
into the system if called for by the ISAM parameter 
line of the CONFIG.SYS file. It provides the 
system file manager with the necessary facilities 
to handle ISAM files. 


Key is used in two senses in this manual: as a 
name for the plastic buttoms on the keyboards, 
and as the keyword of an ISAM file. An ISAM 
key is the string of characters by which a record 
is filed; keys are maintained in alphabetical (ASCII) 
order by the ISAM manager. 


Less than or equal to, a relational operator. Less 
than or equal to returns TRUE only if the value 
of the expression to its left is less than or equal 
to the value of the expression to its right. String 
comparisons are by ASCII order. 


A statement assigning a value to a variable, as in 
"LET A=3". 


Logical file number assigned to a file by an OPEN 
statement. The LFN is then used in READ and 
WRITE and other I/O statements to identify the 
file. 


Note: This glossary is in ASCII order. 
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LINE LABEL 


LOGICAL EXPRESSION 


LOGICAL OPERATORS 


LOWER CASE ALPHABETICS 


MAIN ROUTINE 


MATHEMATICAL EXPRESSION 


MATHEMATICAL OPERATORS 
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A number or name identifying a program line. Line 
labels (or statement labels) are used in transfer 
statements to identify the target of the transfer. 
They are also used in RESTORE statements to 
identify the appropriate DATA statement. 


The directive of the STAR BASIC statement which 
turns the compiler's printed output on or off. A 
LIST OFF statement will turn off printed or file 
output of the compiler listing, while LIST ON will 
turn it back on. Normally used with already- 


debugged external subroutines and functions. 


A record is locked if it has been read with the 
lock option set to 1 (its default value). A locked 
record may not be accessed by any other user. 
Operations which change a record (rewriting or 
deleting it) in ISAM files require the record be 
locked. Record locking does not apply to sequential 
files. 


A conditional expression containing one or more 
of the logical operators (AND OR NOT). 


The logical connectives: AND OR NOT. The 
logical operators are used only in conditional state- 
ments, linking (or negating) conditional expressions. 
They return TRUE or FALSE as values, according 
to the rules of formal logic. 


The lower case (small) alphabet characters: 


abedefghijklmnopqrstuvwxyz 


The central control routine of a program, which 
may contain internal subroutines. Program struc- 
ture often consists of a main routine and a group 
of external subroutines which are called by the 
main routine. 


An element, or a mathematical expression preceded 
by - (the negation operator), or two mathematical 
expressions linked by a binary mathematical opera- 
tor. 


The arithmetic operators and the string operator: 
+ addition, - subtraction, * multiplication, / divi- 
sion, \ remaindering, & concatenation, and the only 
unary mathematical operator, - negation. Mathe- 
matical operators link mathematical expressions. 


Note: This glossary is in ASCII order. 
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MULTIPLICATION 


NE 


NEGATION 


NON-FATAL ERRORS 


NUMERIC ELEMENT 
( ) NUMERIC LABEL 


NUMERICS 


ON ERROR 


ON GOSUB 


ON GOTO 


Glossary 


*, a binary mathematical operator. Multiplication 
adds the numeric value of the mathematical expres- 
sion on its left to itself the number of times equal 
to the numeric value of the mathematical expres- 
sion to its right. 


Not equal, a relational operator. Not equal returns 
TRUE only if the value of the mathematical expres- 
sion on its left is not identical to the value of the 
mathematical expression on its right. 


-, the only unary mathematical operator, performs 
negation by reversing the sign of the numeric value 
of the mathematical expression on its right. 


An "error" which causes automatic corrective 
action by the system but which does not halt 
execution. A number which is too large, for 
instance, causes the value to be taken as the largest 
possible value, .99999999999999 E63. 


A numeric constant, numeric variable, numeric 
array, or numeric function. 


A statement label made up of numbers only, option- 
ally followed by a colon. 


The digits: 0123456789 


Sets a trap for errors. If an error occurs after 
an ON ERROR statement has been encountered, 
the executable statement following the words "ON 
ERROR" will be executed. (Exception: errors may 
also be trapped by I/O keywords EOF and ERL.) 


A computed transfer identical to an ON GOTO 
except that a GOSUB rather than a GOTO is 
performed. 


A computed transfer. "ON I GOTO 1,2,3,4,5" 
transfers to line labels 1 or 2 or 3 or 4 or 5, with 
the target being picked by the value of I and the 
order of the labels on the list. 


cy Note: This glossary is in ASCII order. 
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OPEN 


OPERATOR 


OUTPUT 


PARITY 


PARTITION 


PERIOD 


PRECEDENCE 


PRINT 


PUBSYS.SRC 


READ 
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To prepare a file for use. To be used, data files 
must be OPEN, which identifies the file with a 
logical file number (LFN), notifies the file manager 
that the file is open and that the LFN is assigned, 
and sets the access option. 


Mathematical, relational, logical or grouping con- 
nectors which form expressions by linking con- 
stants, variables, arrays, functions and other 
expressions. 


To take information out of the F-85. Data can 
be output to the video display, to the printer, or 
to a disk file. See also, INPUT/OUTPUT. 


A check on data transmission errors. The number 
of 1 bits in a characters are added together and 
a parity bit is used to make the total even (EVEN 
parity) or odd (ODD parity). If no parity bit is 
used, the NONE option is used in configuring the 
multi-communications port. 


A subsection of user memory space reserved for 
a program or set of programs, assigned to a 
terminal. Partitions are defined in partition control 
files, used with multitasking RUN. The control 
file defines how much memory and common 
memory area is allocated to the partition, how 
many files are allowed open at any one time, what 
the main program for the partition will be. 


The period symbol: . 


What comes first. Operator precedence is: first 
grouping, then negation, then multiplication, divi- 
sion and remaindering, then addition and subtrac- 
tion, then concatenation, then all relational opera- 
tors, then NOT, then AND or OR, then left to 
right. 


To display information on the video screen. 


The public symbols text file. This file contains a 
listing of the public symblos of the DX-85M 
operating system. This file is only useful to 
assembly-level programmers. 


To input information from DATA statements (inter- 
nal I/O) or from disk (file record I/O). 


Note: This glossary is in ASCII order. 
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REMAINDERING Remaindering, a binary mathematical operator. 
Remaindering divides the numerie value of the 
mathematical expression on its left by the numeric 
value of the mathematical expression on its right 
and returns the remainder. 


REWIND To set the read and write pointers of a file back 
to its beginning. 


ROUTINE A set of instructions which accomplish a desired 
action. A main routine is the control program, 
which calls subroutines. Subroutines can be internal 
(within the main routine), or external (headed by 
a SUB), or functions (headed by a FUN statement). 


RUN/RUNB The DX-85M run-time monitor. RUN executes 
program from object code file (created by the 
STAR BASIC compiler from source programs). 


STAR BASIC The F-85 programming language. It is a business 
oriented, sophisticated, flexible English-like high 
level language with extensive file handling 
capabilities, fast string and numeric manipulation 
and flexible display controls. 


( STAR BASIC CHARACTER An alphabetic or a numeric or a period or a symbol. 
STARTU.SYS The system startup program. STARTU.SYS is 

loaded and run immediately after the system is 

configured, to initialize the system. If a 


$AUTOSTART file is present, STARTU.SYS runs 
the input routine to set the date in the system 
clock and loads the keyboard buffer with the 
contents of the $AUTOSTART file. 


STATEMENT A well-formed "sentence" in STAR BASIC. Each 
statement performs a_ single (quite possibly 
complex) task. 


STATEMENT BODY A statement, ignoring the label (if any). Statement 
bodies ean be blank, or ean consist of a well-formed 
"sentence" in STAR BASIC. 


STATEMENT LABEL A LINE LABEL attached to a statement in a source 
program (line labels can also be used on an other- 
wise blank line). 


( Note: This glossary is in ASCII order. 
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STATEMENT TYPE The statement types are null, comment statements, 
assignment statements, declarative statements, 
looping or conditional statements, transfer or 
subroutine statements, error handling statements 
or input/output statements. 


STOP To end execution. 


STOP BIT The end of character signal used in data trans- 
mission. When data is sent to an external peri- 
pheral device (a terminal or printer) either one, 
one and a half, or two "stop bits" signal the end 
of each character to the receiving device. Trans- 
mission rates of 110 baud or less usually use 2 
stop bits, while most higher rates use 1 stop bit. 
Some IBM devices use 1.5. 


STRING A series of characters. Constants, variables, 
arrays, functions and expressions may be of string 
or numeric type. Numeric type requires only 
numeric characters; string type allows any charac- 
ter. 


STRING ELEMENT A string constant, string variable, string array or 
string function. 


STRING LITERAL A string constant. A literal is something whose 
name and value are the same; a string literal is 
therefore a string of characters whose value is 


itself. 
SUB SUB statements head every external subroutine. 
SUBTRACTION -, a numeric mathematical operator, performs sub- 


traction by negating the numeric value of the 
mathematical expression on its right and adding it 
to the numeric value of the mathematical expres- 
sion on its left. 


SYMBOLS The following symbols: (blank) "$& =+*/\ (),.3:/ 


Note: This glossary is in ASCII order. 
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QO TITLE A STAR BASIC statement which puts an identifying 
header at the top left of the compiler listing. 
Used to help document the program by identifying 
the various routines. TITLE statements may also 
cause a page eject. 


TRANSPARENCY MODE The system uses coding for video display and printer 
control which does not completely match standard 
ASCII codes. If the multi-communications port is 
configured in transparency mode, the internal 
coding will be transmitted to the peripheral device. 
If it is not in transparency mode, the non-standard 
code will be converted to standard ASCII before 
transmission. 


UNARY OPERATOR An operator with expressions on only one side. -, 
negation, a numeric mathematical operator; and 
NOT, a logical operator, are the only unary opera- 
tors in STAR BASIC. 


UNLOCK To release the LOCK on a record caused by a 
READ statement with the LOCK keyword set to 
1 (the default value). 


UPPER CASE ALPHABETICS The upper case (big) alphabet characters: 
¢ ) ABCDEFGHIJKLMNOPQRSTUVWXYZ 


USER-DEFINED FUNCTION Headed by a FUN statement, user-defined functions 
are written as external subroutines but are invoked 
by the use of the function name in an expression. 
The EXIT statement in FUN subroutines assigns a 
value to the function name. 


VARIABLE ‘A name which identifies a single value (which may 
change, of course). A variable can be seen as an 
array with only a single value. 


WRITE To send data to the printer or to a disk file. 


% Remaindering, a binary mathematical operator. 
Remaindering divides the numeric value of the 
mathematical expression on its left by the numeric 
value of the mathematical expression on its right 
and returns the remainder. 


Note: This glossary is in ASCII order. 
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Note: 


E-16 


The continuation symbol. If used at the extreme 
left margin of a line it marks the line as the 
continuation of the previous line. 


A remark. (or REM or REMARK) statements 
document a program. 


This glossary is in ASCII order. 
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